RemNote MCP Server

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, 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.

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 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 Cowork - Cloud-based (requires remote access