remnote-mcp-server
MCP server and CLI for RemNote, with guarded note deletion. Fork of robert7/remnote-mcp-server (MIT).
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bberkesever--remnote-mcp-server)HTML
<a href="/listings/bberkesever--remnote-mcp-server"><img src="/api/listings/bberkesever--remnote-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md).
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](https://github.com/robert7/remnote-mcp-bridge) 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](docs/guides/configuration.md) - Overview and generic setup - [Codex TUI / Codex.app](docs/guides/configuration-codex.md) - HTTP MCP, stdio proxy, and `remnote-cli` skill setup - [Claude Desktop / Cowork Local MCPB](docs/guides/configuration-claude-desktop-local-mcpb.md) - Preferred local desktop setup, no public HTTPS required - [Claude Desktop / Cowork Remote Connector](docs/guides/configuration-claude-desktop-cowork.md) - Remote connector setup when local MCPB is not applicable - [Claude Code CLI](docs/guides/configuration-claude-code-CLI.md) - Claude Code local MCP setup - [ChatGPT](docs/guides/configuration-chatgpt.md) - ChatGPT Apps configuration - [Accomplish](docs/guides/configuration-accomplish.md) - Accomplish (Openwork) configuration - [Generic stdio MCP clients](docs/guides/configuration.md#stdio-mcp-clients) - Use `remnote-mcp-stdio`
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 366 lines
- # RemNote MCP Server (bberkesever fork)
- > **This is a fork.** It is based on [robert7/remnote-mcp-server](https://github.com/robert7/remnote-mcp-server)
- > (MIT) by Robert Spiegel, with additions by [bberkesever](https://github.com/bberkesever), notably the guarded
- > `remnote_delete_note` tool (`dryRun` by default, `expectedDescendantCount` confirmation). Use it with the matching
- > bridge fork, [bberkesever/remnote-mcp-bridge](https://github.com/bberkesever/remnote-mcp-bridge).
- 
- 
- [](https://www.npmjs.com/package/remnote-mcp-server)
- [](https://codecov.io/gh/robert7/remnote-mcp-server)
- MCP server and CLI package that bridges AI agents, local scripts, and coding harnesses to
- [RemNote](https://remnote.com/) via the [RemNote Automation Bridge
- plugin](https://github.com/robert7/remnote-mcp-bridge).
- > **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](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md),
- > [plugin install guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/install-plugin-via-marketplace-beginner.md),
- > [local plugin guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/development-run-plugin-locally.md), and
- > [server installation guide](docs/guides/installation.md).
- > After setup, see the [agent validation prompts](docs/agent-validation-prompts/README.md) 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](https://github.com/robert7/remnote-mcp-server/issues) 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](docs/demo.md)** · **[Advanced Use Cases](docs/advanced-use-cases.md)**
- ### Two-Component Architecture
- This system consists of **two separate runtime components** that work together:
- 1. **[RemNote Automation Bridge](https://github.com/robert7/remnote-mcp-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 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](skills/remnote/SKILL.md) 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](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/connection-lifecycle.md).
- ### How It Works
- ```text
- 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](docs/guides/remote-access.md) 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](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md).
- ```bash
- npm install -g remnote-mcp-server
- ```
- The package installs these commands:
- ```bash
- remnote-mcp-server --version
- remnote-cli --version
- remnote-mcp-stdio --version
- ```
- ### 2. Install the RemNote Plugin
- Install the official [MCP/OpenClaw Automation Bridge plugin](https://github.com/robert7/remnote-mcp-bridge) 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
- ```bash
- remnote-mcp-server
- ```
- Expected output:
- ```text
- 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:
- ```bash
- 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:
- ```bash
- 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](docs/guides/configuration.md) - Overview and generic setup
- - [Codex TUI / Codex.app](docs/guides/configuration-codex.md) - HTTP MCP, stdio proxy, and `remnote-cli` skill setup
- - [Claude Desktop / Cowork Local MCPB](docs/guides/configuration-claude-desktop-local-mcpb.md) - Preferred local desktop setup, no public HTTPS required
- - [Claude Desktop / Cowork Remote Connector](docs/guides/configuration-claude-desktop-cowork.md) - Remote connector setup when local MCPB is not applicable
- - [Claude Code CLI](docs/guides/configuration-claude-code-CLI.md) - Claude Code local MCP setup
- - [ChatGPT](docs/guides/configuration-chatgpt.md) - ChatGPT Apps configuration
- - [Accomplish](docs/guides/configuration-accomplish.md) - Accomplish (Openwork) configuration
- - [Generic stdio MCP clients](docs/guides/configuration.md#stdio-mcp-clients) - Use `remnote-mcp-stdio`
- ## Documentation
- ### Getting Started
- - **[Installation Guide](docs/guides/installation.md)** - Complete installation instructions
- - **[Bridge / Consumer Version Compatibility
- Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md)**
- \- Match server version to installed bridge plugin version (`0.x` semver)
- - **[Bridge Connection Lifecycle](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/connection-lifecycle.md)** - Canonical bridge connect/retry behavior
- - **[Configuration Guide](docs/guides/configuration.md)** - Configure Claude Code CLI, Accomplish, and other clients
- - **[Codex Configuration Guide](docs/guides/configuration-codex.md)** - Set up Codex TUI and Codex.app with RemNote
- - **[ChatGPT Configuration Guide](docs/guides/configuration-chatgpt.md)** - Set up ChatGPT Apps with your MCP server
- - **[Demo and Screenshots](docs/demo.md)** · **[Advanced Use Cases](docs/advanced-use-cases.md)** - See simple demos and longer workflows
- ### Usage
- - **[remnote-mcp-server Command Reference](docs/guides/remnote-mcp-server-command-reference.md)** - Server executable, daemon, and launchd options
- - **[remnote-cli Command Reference](docs/guides/remnote-cli-command-reference.md)** - Shell command reference for the bundled CLI
- - **[MCP Tools Reference](docs/guides/tools-reference.md)** - Detailed reference for all 9 RemNote tools
- - **[Remote Access Setup](docs/guides/remote-access.md)** - Expose server for cloud clients or remote connector flows
- (ngrok, etc.)
- ### Help & Advanced
- - **[Troubleshooting](docs/guides/troubleshooting.md)** - Common issues and solutions
- - **[Architecture](docs/architecture.md)** - Design rationale and technical architecture
- ### Development
- - **[Development Setup](docs/guides/development-setup.md)** - Contributing guide for developers
- - **[Testing Strategy](docs/guides/testing-strategy.md)** - Three-level testing model: local quality checks, maintainer
- live integration, and end-user agent validation
- - **[Integration Testing](docs/guides/integration-testing.md)** - Canonical shared workflow for updating and running MCP server + CLI integration coverage against live RemNote
- - **[Publishing Guide](docs/npm-publishing.md)** - npm publishing process (maintainers only)
- ## Available MCP Tools
- | Tool | Description |
- |---------------------------|-----------------------------------------------------------------------------|
- | `remnote_create_note` | Create notes, markdown trees, or flashcards with real aliases, optional exact tag Rem IDs, and root document status |
- | `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_get_media` | Retrieve one validated RemNote-managed image as MCP-native image content |
- | `remnote_update_note` | Update title and add/remove real aliases |
- | `remnote_set_document_status` | Preview or set document status while preserving concept/card status |
- | `remnote_insert_children` | Insert child Rems at deterministic positions |
- | `remnote_replace_children` | Replace direct content children while preserving parent metadata |
- | `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](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) 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](docs/guides/tools-reference.md) for detailed usage and examples.
- ## Supported AI Clients
- - **[Claude Code CLI](https://claude.com/claude-code)** - 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](https://github.com/accomplish-ai/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:**
- ```text
- Create a note about "Project Ideas" with content:
- - AI-powered note taking
- - Personal knowledge management
- ```
- **Search:**
- ```text
- Search my RemNote for notes about "machine learning"
- ```
- **Update notes:**
- ```text
- Add a tag "important" to note abc123
- ```
- **Journal entries:**
- ```text
- Add to my journal: "Completed the RemNote MCP integration"
- ```
- See the [Tools Reference](docs/guides/tools-reference.md) 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)
- - `REMNOTE_MEDIA_ROOTS` - Allowed RemNote media roots, separated by the platform path delimiter; defaults to discovered
- `~/remnote/remnote-*/files` directories. Equivalent repeatable CLI flag: `--media-root`.
- ### Custom Ports
- ```bash
- remnote-mcp-server --http-port 3003 --ws-port 3004
- ```
- After changing ports, update your MCP client configuration and RemNote plugin settings.
- ### Background Daemon
- ```bash
- 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](docs/guides/remnote-mcp-server-command-reference.md) 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](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md)
- See the [Troubleshooting Guide](docs/guides/troubleshooting.md) 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](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md)).
- ```bash
- 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:**
- ```bash
- 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](docs/guides/development-setup.md) for complete instructions.
- Pull requests that affect bridge-consumer behavior should follow the shared PR rules in the bridge repo: [Pull Request Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/pull-request-guide.md). 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](docs/guides/testing-strategy.md).
- ## Related Projects
- - [RemNote Automation Bridge](https://github.com/robert7/remnote-mcp-bridge) - Browser plugin for RemNote integration
- - [Model Context Protocol](https://modelcontextprotocol.io/) - Open protocol for AI-application integration
- ## License
- MIT
- ## Links
- - [Documentation](docs/guides/) - Complete documentation
- - [GitHub Issues](https://github.com/robert7/remnote-mcp-server/issues) - Bug reports and feature requests
- - [npm Package](https://www.npmjs.com/package/remnote-mcp-server) - Official npm package
- - [CHANGELOG](CHANGELOG.md) - Version history and roadmap
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.