RemNote MCP Server

MCP server and CLI package that bridges AI agents, local scripts, and coding harnesses to
RemNote via the RemNote Automation Bridge
plugin.

Connection issue? Check the RemNote bridge plugin and server versions first. Use the official
MCP/OpenClaw Automation Bridge by Robert Spiegel in RemNote, and run a compatible remnote-mcp-server on the same
0.x minor line. Wrong plugin flavors or mismatched versions can disconnect with a 1008 compatibility message.
If Marketplace and npm releases are temporarily out of
sync, pin the matching server package or run matching bridge/server checkouts from source. Start with the
version compatibility guide,
plugin install guide,
local plugin guide, and
server installation guide.
After setup, see the agent validation prompts to verify that your chosen AI
agent can use the installed RemNote MCP tools end to end.
If the guides do not resolve your problem, open an issue with
the relevant versions, setup path, observed behavior, and exact error/status message.

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). The same npm package also provides remnote-cli, a command-line MCP client
for local scripts and coding harnesses, and remnote-mcp-stdio, a stdio MCP proxy for clients that cannot consume
Streamable HTTP directly. Create notes, hierarchical markdown trees, and RemNote-native flashcards; search and read
your knowledge base; update existing notes; and maintain your daily journal through MCP tools or shell commands.
See AI agent examples in action with
RemNote: Demo and Screenshots · Advanced Use Cases

Two-Component Architecture

This system consists of two separate runtime components that work together:

RemNote Automation 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 package that provides remnote-mcp-server for MCP
HTTP clients, remnote-mcp-stdio for stdio MCP clients, and remnote-cli for command-line workflows

The remnote-cli and remnote-mcp-stdio commands are not second RemNote-facing servers. They call the MCP endpoint
exposed by remnote-mcp-server.

For OpenClaw/Hermes AI agents and other command-driven local automation, remnote-cli is the direct path: point the
agent at the bundled RemNote CLI skill and keep the MCP server running locally.

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
AI agents (stdio) -> remnote-mcp-stdio -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
CLI commands -> remnote-cli -> 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
Provides remnote-mcp-stdio as a local stdio MCP proxy for clients that need stdio transport
Provides remnote-cli as a bundled command-line MCP client for local automation
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. Claude Desktop and Claude
Cowork can use the bundled local MCPB extension when desktop extensions are enabled. Cloud-based clients, web/mobile
surfaces, and managed Claude deployments without local MCPB 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 exact tag Rem ID searches with ancestor context
Read Notes - Retrieve note content in markdown or structured form with configurable traversal depth
Update Notes - Modify titles, insert or replace hierarchical content, and manage tags by exact Rem ID
Journal Entries - Append timestamped daily entries with hierarchical markdown content and optional exact tag Rem IDs
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

The package installs these commands:

remnote-mcp-server --version
remnote-cli --version
remnote-mcp-stdio --version

2. Install the RemNote Plugin

Install the official MCP/OpenClaw Automation Bridge plugin in your
RemNote app. If installing from the RemNote Marketplace, verify the plugin name and author; similarly named
MCP Bridge variants may be incompatible with this server and cause connection loops or 1008 disconnects. Configure
the plugin to connect to ws://127.0.0.1:3002.

3. Start the Server

remnote-mcp-server

Expected output:

RemNote MCP Server v<version> listening { wsPort: 3002, httpPort: 3001 }

Keep this terminal running.

For a background server that survives terminal close and writes to a stable log file:

remnote-mcp-server daemon start
remnote-mcp-server daemon status
remnote-mcp-server daemon logs
remnote-mcp-server daemon stop

Daemon state and logs default to ~/.remnote-mcp-server/. On macOS, install a login LaunchAgent for restart/login
persistence:

remnote-mcp-server daemon install-launchd

After installing the LaunchAgent, remnote-mcp-server daemon status|start|stop|restart controls the launchd service.

4. Configure Your AI Client

Configuration Guide - Overview and generic setup
- Codex TUI / Codex.app - HTTP MCP, stdio proxy, and remnote-cli skill setup
- Claude Desktop / Cowork Local MCPB - Preferred local desktop setup, no public HTTPS required
- Claude Desktop / Cowork Remote Connector - Remote connector setup when local MCPB is not applicable
- Claude Code CLI - Claude Code local MCP setup
- ChatGPT - ChatGPT Apps configuration
- Accomplish - Accomplish (Openwork) configuration
- Generic stdio MCP clients - Use remnote-mcp-stdio

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
Codex Configuration Guide - Set up Codex TUI and Codex.app with RemNote
ChatGPT Configuration Guide - Set up ChatGPT Apps with your MCP server
Demo and Screenshots · Advanced Use Cases - See simple demos and longer workflows

Usage

remnote-mcp-server Command Reference - Server executable, daemon, and launchd options
remnote-cli Command Reference - Shell command reference for the bundled CLI
MCP Tools Reference - Detailed reference for all 9 RemNote tools
Remote Access Setup - Expose server for cloud clients or remote connector flows
(ngrok, etc.)

Help & Advanced

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

Development

Development Setup - Contributing guide for developers
Testing Strategy - Three-level testing model: local quality checks, maintainer
live integration, and end-user agent validation
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 optional exact tag Rem IDs
`remnote_search`	Search knowledge base with full-text search, parent context, and optional tag IDs/names
`remnote_search_by_tag`	Search by exact tag Rem ID with ancestor-context resolution
`remnote_read_note`	Read note by ID with metadata, optional tag IDs/names, and markdown or structured content
`remnote_update_note`	Update title
`remnote_insert_children`	Insert child Rems at deterministic positions
`remnote_replace_children`	Replace direct children when destructive replacement is enabled
`remnote_update_tags`	Add or remove tags by exact tag Rem ID
`remnote_append_journal`	Append hierarchical content to today's daily document with optional tag Rem IDs
`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.

The server uses @modelcontextprotocol/sdk and supports current MCP protocol negotiation, including 2025-11-25.
Do not confuse MCP protocol versions with remnote-mcp-server or bridge plugin package versions; package versions use
0.x semver and should usually match by minor line.

See the Tools Reference for detailed usage and examples.

Supported AI Clients

Claude Code CLI - Local terminal-based agent
Codex TUI / Codex.app - Local OpenAI coding agent clients
Claude Desktop / Cowork - Local MCPB clients when desktop extensions are enabled, or remote connector clients
when local MCPB is not applicable
Accomplish - Task-based MCP client (formerly Openwork)
Any MCP client supporting Streamable HTTP transport
Any local MCP client supporting stdio transport through remnote-mcp-stdio
Any local command runner that can call remnote-cli

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.

Background Daemon

remnote-mcp-server daemon start

Default log: ~/.remnote-mcp-server/remnote-mcp-server.log
Duplicate starts are treated as already running when the daemon PID is alive.
If the configured HTTP or WebSocket port is already occupied, startup fails before spawning a second server.
Use remnote-mcp-server daemon stop for graceful shutdown.
Use remnote-mcp-server daemon install-launchd on macOS to keep the server running across login and unexpected
exits.
When launchd is installed, the same daemon status/start/stop/restart commands control the launchd service.

See remnote-mcp-server Command 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
./link-cli.sh
# Later, remove the local links for package executables:
./unlink-cli.sh

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 and server-package behavior aligned for shared functionality changes.

For the three-level testing model and links to each verification path, see the Testing Strategy.

Related Projects

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

License

MIT

remnote-mcp-server