RemNote MCP Server

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

This is a working solution, but still experimental. 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, search 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.

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.

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 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 - Create new notes with optional parent hierarchy and tags
• Search Knowledge Base - Full-text search with configurable result limits
• Read Notes - Retrieve note content with configurable child depth
• Update Notes - Modify titles, append/replace content, add/remove tags
• Journal Entries - Append timestamped entries to daily documents
• 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 Cowork - Cloud-based (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)
• 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 8 RemNote tools
• Remote Access Setup - Expose server for Claude 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 - End-to-end validation against a live RemNote instance
• Publishing Guide - npm publishing process (maintainers only)

Available MCP Tools

| Tool | Description | |---------------------------|------------------------------------------------| | remnote_create_note | Create new notes with optional parent and tags | | remnote_search | Search knowledge base with full-text search | | remnote_search_by_tag | Search by tag with ancestor-context resolution | | remnote_read_note | Read note by ID with configurable depth | | remnote_update_note | Update title, append/replace content, or modify tags | | remnote_append_journal | Append to today's daily document | | remnote_get_playbook | Get recommended MCP usage/navigation playbook | | remnote_status | Check connection status and statistics |

See the Tools Reference for detailed usage and examples.

Supported AI Clients

• Claude Code CLI - Local terminal-based agent
• Claude Cowork - Cloud-based workspace (requires 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.

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