RemNote Server

npm version codecov

MCP server that bridges AI agents (e.g. Claude Code) to RemNote via the RemNote Automation Bridge plugin.

If you run into any issues, please report them here.

What is This?

The RemNote MCP Server enables AI assistants like Claude Code to interact directly with your RemNote knowledge base through the Model Context Protocol (MCP). Create notes, hierarchical markdown trees, and RemNote-native flashcards; search and read your knowledge base; update existing notes; and maintain your daily journal, all through conversational commands.

For some agentic workflows or CLI-first automation, the companion app remnote-cli may be a better fit than running a full MCP server. In particular, coding harnesses (Claude Code, GitHub Copilot CLI, Codex CLI, etc.) can use remnote-cli with zero config — paste one prompt that loads the skill file and the agent handles the rest. See Use RemNote from Any Coding Harness.

Demo

See AI agent examples in action with RemNote: View Demo →

Two-Component Architecture

This system consists of two separate components that work together:

1. RemNote Automation Bridge - A RemNote plugin that runs in your browser or RemNote desktop app and exposes RemNote API functionality via WebSocket
2. RemNote MCP Server (this project) - A standalone server that connects your AI assistant to the bridge using MCP protocol

Both components are required for AI integration with RemNote.

For the detailed bridge connection lifecycle, retry phases, and wake-up triggers, use the bridge repo as the source of truth: Connection Lifecycle Guide.

How It Works

AI agents (HTTP) ↔ MCP HTTP Server :3001 ↔ WebSocket Server :3002 ↔ RemNote Plugin ↔ RemNote

The server acts as a bridge:

• Communicates with AI agents via Streamable HTTP transport (MCP protocol) - supports both local and remote access
• HTTP server (port 3001) manages MCP sessions for multiple concurrent agents
• WebSocket server (port 3002) connects to the RemNote browser plugin
• Translates MCP tool calls into RemNote API actions

Multi-Agent Support: Multiple AI agents can connect simultaneously to the same RemNote knowledge base. Each agent gets its own MCP session while sharing the WebSocket bridge.

Remote Access: By default, the server binds to localhost (127.0.0.1) for local AI agents. Cloud-based services like Claude Desktop and Claude Cowork require remote access—use tunneling tools like ngrok to expose the HTTP endpoint securely. The WebSocket connection always stays local for security. See Remote Access Guide for setup.

Features

• Create Notes & Flashcards - Create simple notes, hierarchical markdown trees, or RemNote-native flashcards
• Search Knowledge Base - Run full-text searches or tag-based searches with ancestor context
• Read Notes - Retrieve note content in markdown or structured form with configurable traversal depth
• Update Notes - Modify titles, append or replace hierarchical content, and manage tags
• Journal Entries - Append timestamped daily entries, including hierarchical markdown content
• Agent Playbook - Return built-in navigation and safety guidance for MCP clients
• Connection Status - Check server and plugin connection health

Quick Start

1. Install the Server

Version compatibility (0.x semver): install a remnote-mcp-server version compatible with your installed RemNote Automation Bridge plugin version. See the Bridge / Consumer Version Compatibility Guide.

npm install -g remnote-mcp-server

2. Install the RemNote Plugin

Install the RemNote Automation Bridge plugin in your RemNote app. Currently available from GitHub; registration in the RemNote marketplace is pending approval. Configure the plugin to connect to ws://127.0.0.1:3002.

3. Start the Server

remnote-mcp-server

Expected output:

RemNote MCP Server v0.2.1 listening { wsPort: 3002, httpPort: 3001 }

Keep this terminal running.

4. Configure Your AI Client

• Configuration Guide - Overview and generic setup
  • ChatGPT - ChatGPT Apps configuration
  • Claude Desktop / Cowork - Remote connector setup (requires remote access setup)
  • Claude Code CLI - Detailed Claude Code CLI configuration
  • Accomplish - Accomplish (Openwork) configuration

Documentation

Getting Started

• Installation Guide - Complete installation instructions
• Bridge / Consumer Version Compatibility Guide - Match server version to installed bridge plugin version (0.x semver)
• Bridge Connection Lifecycle - Canonical bridge connect/retry behavior
• Configuration Guide - Configure Claude Code CLI, Accomplish, and other clients
• ChatGPT Configuration Guide - Set up ChatGPT Apps with your MCP server
• Demo & Screenshots - See the server in action with different AI clients

Usage

• CLI Options Reference - Command-line options and environment variables
• MCP Tools Reference - Detailed reference for all 9 RemNote tools
• Remote Access Setup - Expose server for Claude Desktop / Cowork (ngrok, etc.)

Help & Advanced

• Troubleshooting - Common issues and solutions
• Architecture - Design rationale and technical architecture

Development

• Development Setup - Contributing guide for developers
• Integration Testing - Canonical shared workflow for updating and running MCP server + CLI integration coverage against live RemNote
• Publishing Guide - npm publishing process (maintainers only)

Available MCP Tools

Tool	Description
remnote_create_note	Create notes, markdown trees, or flashcards with title, content, parent, and tags
remnote_search	Search knowledge base with full-text search and parent-context metadata; tags remain optional and SDK-limited
remnote_search_by_tag	Search by tag with ancestor-context resolution
remnote_read_note	Read note by ID with metadata and markdown or structured content; readable tags remain SDK-limited
remnote_update_note	Update title, append/replace content, or modify tags
remnote_append_journal	Append hierarchical content to today's daily document
remnote_read_table	Read Advanced Table columns, rows, and typed property metadata
remnote_get_playbook	Get recommended MCP usage/navigation playbook
remnote_status	Check connection status and statistics

Tools that declare an outputSchema return MCP structuredContent plus a JSON content text block for compatibility. See the MCP tools specification for the protocol contract.

See the Tools Reference for detailed usage and examples.

Supported AI Clients

• Claude Code CLI - Local terminal-based agent
• Claude Desktop / Cowork - Remote connector clients (require remote access)
• Accomplish - Task-based MCP client (formerly Openwork)
• Any MCP client supporting Streamable HTTP transport

Example Usage

Create notes:

Create a note about "Project Ideas" with content:
- AI-powered note taking
- Personal knowledge management

Search:

Search my RemNote for notes about "machine learning"

Update notes:

Add a tag "important" to note abc123

Journal entries:

Add to my journal: "Completed the RemNote MCP integration"

See the Tools Reference for more examples.

Configuration

Environment Variables

• REMNOTE_HTTP_PORT - HTTP MCP server port (default: 3001)
• REMNOTE_HTTP_HOST - HTTP server bind address (default: 127.0.0.1)
• REMNOTE_WS_PORT - WebSocket server port (default: 3002)

Custom Ports

remnote-mcp-server --http-port 3003 --ws-port 3004

After changing ports, update your MCP client configuration and RemNote plugin settings.

See CLI Options Reference for all options.

Troubleshooting

Server won't start:

• Check ports aren't in use: lsof -i :3001 and lsof -i :3002
• Verify installation: which remnote-mcp-server

Plugin won't connect:

• Verify plugin settings: WebSocket URL ws://127.0.0.1:3002
• Check server is running: lsof -i :3002

Tools not appearing:

• Verify configuration: claude mcp list
• Restart Claude Code completely
• If this started after upgrades, verify bridge/server version compatibility (0.x minor versions may break); see the Bridge / Consumer Version Compatibility Guide

See the Troubleshooting Guide for detailed solutions.

Contributing & Development

Development setup:

Version compatibility tip: when testing against a local or marketplace-installed bridge plugin, use a server checkout/tag compatible with that bridge plugin version (see the Bridge / Consumer Version Compatibility Guide).

git clone https://github.com/robert7/remnote-mcp-server.git
cd remnote-mcp-server
npm install
npm run build
npm link

Development workflow:

npm run dev          # Watch mode with hot reload
npm test             # Run test suite
./code-quality.sh    # Run all quality checks

See the Development Setup Guide for complete instructions.

Pull requests that affect bridge-consumer behavior should follow the shared PR rules in the bridge repo: Pull Request Guide. In particular, keep bridge/server/CLI parity for shared functionality changes and link related PRs across the affected repos.

For the canonical workflow for updating and running shared live integration coverage, see the Integration Testing Guide.

Related Projects

• RemNote Automation Bridge - Browser plugin for RemNote integration
• Model Context Protocol - Open protocol for AI-application integration

License

MIT

Links

• Documentation - Complete documentation
• GitHub Issues - Bug reports and feature requests
• npm Package - Official npm package
• CHANGELOG - Version history and roadmap