MCP server that bridges AI agents (e.g. Claude Code) to RemNote via the RemNote MCP Bridge plugin.
This is a working proof-of-concept/experimental solution. It "works on my machine" — you're invited to test it and report any bugs or issues.
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.
See AI agent examples in action with RemNote: View Demo →
This system consists of two separate components that work together:
- RemNote MCP Bridge - A RemNote plugin that runs in your browser or RemNote desktop app and exposes RemNote API functionality via WebSocket
- 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.
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.
- 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 content, add/remove tags
- Journal Entries - Append timestamped entries to daily documents
- Connection Status - Check server and plugin connection health
npm install -g remnote-mcp-serverInstall the RemNote MCP 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.
remnote-mcp-serverExpected output:
RemNote MCP Server v0.2.1 listening { wsPort: 3002, httpPort: 3001 }
Keep this terminal running.
- Configuration Guide - Overview and generic setup
- Claude Code CLI - Detailed Claude Code CLI configuration
- Accomplish - Accomplish (Openwork) configuration
- Claude Cowork - Cloud-based (requires remote access setup)
- Installation Guide - Complete installation instructions
- Configuration Guide - Configure Claude Code CLI, Accomplish, and other clients
- Demo & Screenshots - See the server in action with different AI clients
- CLI Options Reference - Command-line options and environment variables
- MCP Tools Reference - Detailed reference for all 6 RemNote tools
- Remote Access Setup - Expose server for Claude Cowork (ngrok, etc.)
- Troubleshooting - Common issues and solutions
- Architecture - Design rationale and technical architecture
- Development Setup - Contributing guide for developers
- Publishing Guide - npm publishing process (maintainers only)
| Tool | Description |
|---|---|
remnote_create_note |
Create new notes with optional parent and tags |
remnote_search |
Search knowledge base with full-text search |
remnote_read_note |
Read note by ID with configurable depth |
remnote_update_note |
Update title, append content, or modify tags |
remnote_append_journal |
Append to today's daily document |
remnote_status |
Check connection status and statistics |
See the Tools Reference for detailed usage and examples.
- 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
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.
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)
remnote-mcp-server --http-port 3003 --ws-port 3004After changing ports, update your MCP client configuration and RemNote plugin settings.
See CLI Options Reference for all options.
Server won't start:
- Check ports aren't in use:
lsof -i :3001andlsof -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
See the Troubleshooting Guide for detailed solutions.
Development setup:
git clone https://github.com/robert7/remnote-mcp-server.git
cd remnote-mcp-server
npm install
npm run build
npm linkDevelopment workflow:
npm run dev # Watch mode with hot reload
npm test # Run test suite
./code-quality.sh # Run all quality checksSee the Development Setup Guide for complete instructions.
- RemNote MCP Bridge Plugin - Browser plugin for RemNote integration
- Model Context Protocol - Open protocol for AI-application integration
MIT
- Documentation - Complete documentation
- GitHub Issues - Bug reports and feature requests
- npm Package - Official npm package
- CHANGELOG - Version history and roadmap