Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bberkesever--remnote-mcp-server/badge.svg)](/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

i

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
  1. # RemNote MCP Server (bberkesever fork)
  2. > **This is a fork.** It is based on [robert7/remnote-mcp-server](https://github.com/robert7/remnote-mcp-server)
  3. > (MIT) by Robert Spiegel, with additions by [bberkesever](https://github.com/bberkesever), notably the guarded
  4. > `remnote_delete_note` tool (`dryRun` by default, `expectedDescendantCount` confirmation). Use it with the matching
  5. > bridge fork, [bberkesever/remnote-mcp-bridge](https://github.com/bberkesever/remnote-mcp-bridge).
  6. ![License](https://img.shields.io/badge/license-MIT-blue)
  7. ![CI](https://github.com/robert7/remnote-mcp-server/actions/workflows/ci.yml/badge.svg)
  8. [![npm version](https://img.shields.io/npm/v/remnote-mcp-server)](https://www.npmjs.com/package/remnote-mcp-server)
  9. [![codecov](https://codecov.io/gh/robert7/remnote-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/robert7/remnote-mcp-server)
  10. MCP server and CLI package that bridges AI agents, local scripts, and coding harnesses to
  11. [RemNote](https://remnote.com/) via the [RemNote Automation Bridge
  12. plugin](https://github.com/robert7/remnote-mcp-bridge).
  13. > **Connection issue? Check the RemNote bridge plugin and server versions first.** Use the official
  14. > **MCP/OpenClaw Automation Bridge** by Robert Spiegel in RemNote, and run a compatible `remnote-mcp-server` on the same
  15. > `0.x` minor line. Wrong plugin flavors or mismatched versions can disconnect with a `1008` compatibility message.
  16. > If Marketplace and npm releases are temporarily out of
  17. > sync, pin the matching server package or run matching bridge/server checkouts from source. Start with the
  18. > [version compatibility guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md),
  19. > [plugin install guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/install-plugin-via-marketplace-beginner.md),
  20. > [local plugin guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/development-run-plugin-locally.md), and
  21. > [server installation guide](docs/guides/installation.md).
  22. > After setup, see the [agent validation prompts](docs/agent-validation-prompts/README.md) to verify that your chosen AI
  23. > agent can use the installed RemNote MCP tools end to end.
  24. > If the guides do not resolve your problem, [open an issue](https://github.com/robert7/remnote-mcp-server/issues) with
  25. > the relevant versions, setup path, observed behavior, and exact error/status message.
  26. ## What is This?
  27. The RemNote MCP Server enables AI assistants like Claude Code to interact directly with your RemNote knowledge base
  28. through the Model Context Protocol (MCP). The same npm package also provides `remnote-cli`, a command-line MCP client
  29. for local scripts and coding harnesses, and `remnote-mcp-stdio`, a stdio MCP proxy for clients that cannot consume
  30. Streamable HTTP directly. Create notes, hierarchical markdown trees, and RemNote-native flashcards; search and read
  31. your knowledge base; update existing notes; and maintain your daily journal through MCP tools or shell commands.
  32. See AI agent examples in action with
  33. RemNote: **[Demo and Screenshots](docs/demo.md)** · **[Advanced Use Cases](docs/advanced-use-cases.md)**
  34. ### Two-Component Architecture
  35. This system consists of **two separate runtime components** that work together:
  36. 1. **[RemNote Automation Bridge](https://github.com/robert7/remnote-mcp-bridge)** - A RemNote plugin that runs in your
  37. browser or RemNote desktop app and exposes RemNote API functionality via WebSocket
  38. 2. **RemNote MCP Server** (this project) - A standalone server package that provides `remnote-mcp-server` for MCP
  39. HTTP clients, `remnote-mcp-stdio` for stdio MCP clients, and `remnote-cli` for command-line workflows
  40. The `remnote-cli` and `remnote-mcp-stdio` commands are not second RemNote-facing servers. They call the MCP endpoint
  41. exposed by `remnote-mcp-server`.
  42. For OpenClaw/Hermes AI agents and other command-driven local automation, `remnote-cli` is the direct path: point the
  43. agent at the bundled [RemNote CLI skill](skills/remnote/SKILL.md) and keep the MCP server running locally.
  44. For the detailed bridge connection lifecycle, retry phases, and wake-up triggers, use the bridge repo as the source of
  45. truth: [Connection Lifecycle Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/connection-lifecycle.md).
  46. ### How It Works
  47. ```text
  48. AI agents (HTTP) -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
  49. AI agents (stdio) -> remnote-mcp-stdio -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
  50. CLI commands -> remnote-cli -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
  51. ```
  52. The server acts as a bridge:
  53. - Communicates with AI agents via Streamable HTTP transport (MCP protocol) - supports both local and remote access
  54. - Provides `remnote-mcp-stdio` as a local stdio MCP proxy for clients that need stdio transport
  55. - Provides `remnote-cli` as a bundled command-line MCP client for local automation
  56. - HTTP server (port 3001) manages MCP sessions for multiple concurrent agents
  57. - WebSocket server (port 3002) connects to the RemNote browser plugin
  58. - Translates MCP tool calls into RemNote API actions
  59. **Multi-Agent Support:** Multiple AI agents can connect simultaneously to the same RemNote knowledge base. Each agent
  60. gets its own MCP session while sharing the WebSocket bridge.
  61. **Remote Access:** By default, the server binds to localhost (127.0.0.1) for local AI agents. Claude Desktop and Claude
  62. Cowork can use the bundled local MCPB extension when desktop extensions are enabled. Cloud-based clients, web/mobile
  63. surfaces, and managed Claude deployments without local MCPB require remote access—use tunneling tools like ngrok to
  64. expose the HTTP endpoint securely. The WebSocket connection always stays local for security. See
  65. [Remote Access Guide](docs/guides/remote-access.md) for setup.
  66. ## Features
  67. - **Create Notes & Flashcards** - Create simple notes, hierarchical markdown trees, or RemNote-native flashcards
  68. - **Search Knowledge Base** - Run full-text searches or exact tag Rem ID searches with ancestor context
  69. - **Read Notes** - Retrieve note content in markdown or structured form with configurable traversal depth
  70. - **Update Notes** - Modify titles, insert or replace hierarchical content, and manage tags by exact Rem ID
  71. - **Journal Entries** - Append timestamped daily entries with hierarchical markdown content and optional exact tag Rem IDs
  72. - **Agent Playbook** - Return built-in navigation and safety guidance for MCP clients
  73. - **Connection Status** - Check server and plugin connection health
  74. ## Quick Start
  75. ### 1. Install the Server
  76. > **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).
  77. ```bash
  78. npm install -g remnote-mcp-server
  79. ```
  80. The package installs these commands:
  81. ```bash
  82. remnote-mcp-server --version
  83. remnote-cli --version
  84. remnote-mcp-stdio --version
  85. ```
  86. ### 2. Install the RemNote Plugin
  87. Install the official [MCP/OpenClaw Automation Bridge plugin](https://github.com/robert7/remnote-mcp-bridge) in your
  88. RemNote app. If installing from the RemNote Marketplace, verify the plugin name and author; similarly named
  89. `MCP Bridge` variants may be incompatible with this server and cause connection loops or `1008` disconnects. Configure
  90. the plugin to connect to `ws://127.0.0.1:3002`.
  91. ### 3. Start the Server
  92. ```bash
  93. remnote-mcp-server
  94. ```
  95. Expected output:
  96. ```text
  97. RemNote MCP Server v<version> listening { wsPort: 3002, httpPort: 3001 }
  98. ```
  99. Keep this terminal running.
  100. For a background server that survives terminal close and writes to a stable log file:
  101. ```bash
  102. remnote-mcp-server daemon start
  103. remnote-mcp-server daemon status
  104. remnote-mcp-server daemon logs
  105. remnote-mcp-server daemon stop
  106. ```
  107. Daemon state and logs default to `~/.remnote-mcp-server/`. On macOS, install a login LaunchAgent for restart/login
  108. persistence:
  109. ```bash
  110. remnote-mcp-server daemon install-launchd
  111. ```
  112. After installing the LaunchAgent, `remnote-mcp-server daemon status|start|stop|restart` controls the launchd service.
  113. ### 4. Configure Your AI Client
  114. - [Configuration Guide](docs/guides/configuration.md) - Overview and generic setup
  115. - [Codex TUI / Codex.app](docs/guides/configuration-codex.md) - HTTP MCP, stdio proxy, and `remnote-cli` skill setup
  116. - [Claude Desktop / Cowork Local MCPB](docs/guides/configuration-claude-desktop-local-mcpb.md) - Preferred local desktop setup, no public HTTPS required
  117. - [Claude Desktop / Cowork Remote Connector](docs/guides/configuration-claude-desktop-cowork.md) - Remote connector setup when local MCPB is not applicable
  118. - [Claude Code CLI](docs/guides/configuration-claude-code-CLI.md) - Claude Code local MCP setup
  119. - [ChatGPT](docs/guides/configuration-chatgpt.md) - ChatGPT Apps configuration
  120. - [Accomplish](docs/guides/configuration-accomplish.md) - Accomplish (Openwork) configuration
  121. - [Generic stdio MCP clients](docs/guides/configuration.md#stdio-mcp-clients) - Use `remnote-mcp-stdio`
  122. ## Documentation
  123. ### Getting Started
  124. - **[Installation Guide](docs/guides/installation.md)** - Complete installation instructions
  125. - **[Bridge / Consumer Version Compatibility
  126. Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md)**
  127. \- Match server version to installed bridge plugin version (`0.x` semver)
  128. - **[Bridge Connection Lifecycle](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/connection-lifecycle.md)** - Canonical bridge connect/retry behavior
  129. - **[Configuration Guide](docs/guides/configuration.md)** - Configure Claude Code CLI, Accomplish, and other clients
  130. - **[Codex Configuration Guide](docs/guides/configuration-codex.md)** - Set up Codex TUI and Codex.app with RemNote
  131. - **[ChatGPT Configuration Guide](docs/guides/configuration-chatgpt.md)** - Set up ChatGPT Apps with your MCP server
  132. - **[Demo and Screenshots](docs/demo.md)** · **[Advanced Use Cases](docs/advanced-use-cases.md)** - See simple demos and longer workflows
  133. ### Usage
  134. - **[remnote-mcp-server Command Reference](docs/guides/remnote-mcp-server-command-reference.md)** - Server executable, daemon, and launchd options
  135. - **[remnote-cli Command Reference](docs/guides/remnote-cli-command-reference.md)** - Shell command reference for the bundled CLI
  136. - **[MCP Tools Reference](docs/guides/tools-reference.md)** - Detailed reference for all 9 RemNote tools
  137. - **[Remote Access Setup](docs/guides/remote-access.md)** - Expose server for cloud clients or remote connector flows
  138. (ngrok, etc.)
  139. ### Help & Advanced
  140. - **[Troubleshooting](docs/guides/troubleshooting.md)** - Common issues and solutions
  141. - **[Architecture](docs/architecture.md)** - Design rationale and technical architecture
  142. ### Development
  143. - **[Development Setup](docs/guides/development-setup.md)** - Contributing guide for developers
  144. - **[Testing Strategy](docs/guides/testing-strategy.md)** - Three-level testing model: local quality checks, maintainer
  145. live integration, and end-user agent validation
  146. - **[Integration Testing](docs/guides/integration-testing.md)** - Canonical shared workflow for updating and running MCP server + CLI integration coverage against live RemNote
  147. - **[Publishing Guide](docs/npm-publishing.md)** - npm publishing process (maintainers only)
  148. ## Available MCP Tools
  149. | Tool | Description |
  150. |---------------------------|-----------------------------------------------------------------------------|
  151. | `remnote_create_note` | Create notes, markdown trees, or flashcards with real aliases, optional exact tag Rem IDs, and root document status |
  152. | `remnote_search` | Search knowledge base with full-text search, parent context, and optional tag IDs/names |
  153. | `remnote_search_by_tag` | Search by exact tag Rem ID with ancestor-context resolution |
  154. | `remnote_read_note` | Read note by ID with metadata, optional tag IDs/names, and markdown or structured content |
  155. | `remnote_get_media` | Retrieve one validated RemNote-managed image as MCP-native image content |
  156. | `remnote_update_note` | Update title and add/remove real aliases |
  157. | `remnote_set_document_status` | Preview or set document status while preserving concept/card status |
  158. | `remnote_insert_children` | Insert child Rems at deterministic positions |
  159. | `remnote_replace_children` | Replace direct content children while preserving parent metadata |
  160. | `remnote_update_tags` | Add or remove tags by exact tag Rem ID |
  161. | `remnote_append_journal` | Append hierarchical content to today's daily document with optional tag Rem IDs |
  162. | `remnote_read_table` | Read Advanced Table columns, rows, and typed property metadata |
  163. | `remnote_get_playbook` | Get recommended MCP usage/navigation playbook |
  164. | `remnote_status` | Check connection status and statistics |
  165. Tools that declare an `outputSchema` return MCP `structuredContent` plus a JSON `content` text block for compatibility.
  166. See the [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) for the
  167. protocol contract.
  168. The server uses `@modelcontextprotocol/sdk` and supports current MCP protocol negotiation, including `2025-11-25`.
  169. Do not confuse MCP protocol versions with `remnote-mcp-server` or bridge plugin package versions; package versions use
  170. `0.x` semver and should usually match by minor line.
  171. See the [Tools Reference](docs/guides/tools-reference.md) for detailed usage and examples.
  172. ## Supported AI Clients
  173. - **[Claude Code CLI](https://claude.com/claude-code)** - Local terminal-based agent
  174. - **Codex TUI / Codex.app** - Local OpenAI coding agent clients
  175. - **Claude Desktop / Cowork** - Local MCPB clients when desktop extensions are enabled, or remote connector clients
  176. when local MCPB is not applicable
  177. - **[Accomplish](https://github.com/accomplish-ai/accomplish)** - Task-based MCP client (formerly Openwork)
  178. - **Any MCP client** supporting Streamable HTTP transport
  179. - **Any local MCP client** supporting stdio transport through `remnote-mcp-stdio`
  180. - **Any local command runner** that can call `remnote-cli`
  181. ## Example Usage
  182. **Create notes:**
  183. ```text
  184. Create a note about "Project Ideas" with content:
  185. - AI-powered note taking
  186. - Personal knowledge management
  187. ```
  188. **Search:**
  189. ```text
  190. Search my RemNote for notes about "machine learning"
  191. ```
  192. **Update notes:**
  193. ```text
  194. Add a tag "important" to note abc123
  195. ```
  196. **Journal entries:**
  197. ```text
  198. Add to my journal: "Completed the RemNote MCP integration"
  199. ```
  200. See the [Tools Reference](docs/guides/tools-reference.md) for more examples.
  201. ## Configuration
  202. ### Environment Variables
  203. - `REMNOTE_HTTP_PORT` - HTTP MCP server port (default: 3001)
  204. - `REMNOTE_HTTP_HOST` - HTTP server bind address (default: 127.0.0.1)
  205. - `REMNOTE_WS_PORT` - WebSocket server port (default: 3002)
  206. - `REMNOTE_MEDIA_ROOTS` - Allowed RemNote media roots, separated by the platform path delimiter; defaults to discovered
  207. `~/remnote/remnote-*/files` directories. Equivalent repeatable CLI flag: `--media-root`.
  208. ### Custom Ports
  209. ```bash
  210. remnote-mcp-server --http-port 3003 --ws-port 3004
  211. ```
  212. After changing ports, update your MCP client configuration and RemNote plugin settings.
  213. ### Background Daemon
  214. ```bash
  215. remnote-mcp-server daemon start
  216. ```
  217. - Default log: `~/.remnote-mcp-server/remnote-mcp-server.log`
  218. - Duplicate starts are treated as already running when the daemon PID is alive.
  219. - If the configured HTTP or WebSocket port is already occupied, startup fails before spawning a second server.
  220. - Use `remnote-mcp-server daemon stop` for graceful shutdown.
  221. - Use `remnote-mcp-server daemon install-launchd` on macOS to keep the server running across login and unexpected
  222. exits.
  223. - When launchd is installed, the same `daemon status/start/stop/restart` commands control the launchd service.
  224. See [remnote-mcp-server Command Reference](docs/guides/remnote-mcp-server-command-reference.md) for all options.
  225. ## Troubleshooting
  226. **Server won't start:**
  227. - Check ports aren't in use: `lsof -i :3001` and `lsof -i :3002`
  228. - Verify installation: `which remnote-mcp-server`
  229. **Plugin won't connect:**
  230. - Verify plugin settings: WebSocket URL `ws://127.0.0.1:3002`
  231. - Check server is running: `lsof -i :3002`
  232. **Tools not appearing:**
  233. - Verify configuration: `claude mcp list`
  234. - Restart Claude Code completely
  235. - If this started after upgrades, verify bridge/server version compatibility (`0.x` minor versions may break); see the
  236. [Bridge / Consumer Version Compatibility
  237. Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md)
  238. See the [Troubleshooting Guide](docs/guides/troubleshooting.md) for detailed solutions.
  239. ## Contributing & Development
  240. **Development setup:**
  241. > **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)).
  242. ```bash
  243. git clone https://github.com/robert7/remnote-mcp-server.git
  244. cd remnote-mcp-server
  245. ./link-cli.sh
  246. # Later, remove the local links for package executables:
  247. ./unlink-cli.sh
  248. ```
  249. **Development workflow:**
  250. ```bash
  251. npm run dev # Watch mode with hot reload
  252. npm test # Run test suite
  253. ./code-quality.sh # Run all quality checks
  254. ```
  255. See the [Development Setup Guide](docs/guides/development-setup.md) for complete instructions.
  256. 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.
  257. For the three-level testing model and links to each verification path, see the [Testing Strategy](docs/guides/testing-strategy.md).
  258. ## Related Projects
  259. - [RemNote Automation Bridge](https://github.com/robert7/remnote-mcp-bridge) - Browser plugin for RemNote integration
  260. - [Model Context Protocol](https://modelcontextprotocol.io/) - Open protocol for AI-application integration
  261. ## License
  262. MIT
  263. ## Links
  264. - [Documentation](docs/guides/) - Complete documentation
  265. - [GitHub Issues](https://github.com/robert7/remnote-mcp-server/issues) - Bug reports and feature requests
  266. - [npm Package](https://www.npmjs.com/package/remnote-mcp-server) - Official npm package
  267. - [CHANGELOG](CHANGELOG.md) - Version history and roadmap

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.