1. Conduid
  2. AI
  3. remnote-server
MCP server · AI

remnote-server

by · github.com/robert7/remnote-mcp-server

MCP server bridge for RemNote knowledge base

Unclaimed agentic-workflowsai-agentshermesmcp-servermodel-context-protocolopenclawremnote
InstallView source
42Fair

Scored yesterday · breakdown

About remnote-server

remnote-server is an MCP server published by git+robert7 in the AI category: mCP server bridge for RemNote knowledge base.

The repository has 30 stars and 0 forks, with the last commit yesterday. Recent commit activity is the strongest signal that reported issues will get attention.

Install

Install
npx remnote-mcp-server
Claude Code
claude mcp add remnote-mcp-server -- npx -y remnote-mcp-server
npx
npx -y remnote-mcp-server

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Tools (14)

remnote_append_journalAppend hierarchical content to today's daily document with optional tag Rem IDs

Parameters not published.

remnote_create_noteCreate notes, markdown trees, or flashcards with real aliases, optional exact tag Rem IDs, and root document status

Parameters not published.

remnote_get_mediaRetrieve one validated RemNote-managed image as MCP-native image content

Parameters not published.

remnote_get_playbookGet recommended MCP usage/navigation playbook

Parameters not published.

remnote_insert_childrenInsert child Rems at deterministic positions

Parameters not published.

remnote_read_noteRead note by ID with metadata, optional tag IDs/names, and markdown or structured content

Parameters not published.

remnote_read_tableRead Advanced Table columns, rows, and typed property metadata

Parameters not published.

remnote_replace_childrenReplace direct content children while preserving parent metadata

Parameters not published.

remnote_searchSearch knowledge base with full-text search, parent context, and optional tag IDs/names

Parameters not published.

remnote_search_by_tagSearch by exact tag Rem ID with ancestor-context resolution

Parameters not published.

Show all 14 tools
remnote_set_document_statusPreview or set document status while preserving concept/card status

Parameters not published.

remnote_statusCheck connection status and statistics

Parameters not published.

remnote_update_noteUpdate title and add/remove real aliases

Parameters not published.

remnote_update_tagsAdd or remove tags by exact tag Rem ID

Parameters not published.

Ask AI

✦

Ask AI about remnote-server

Powered by Claude · Grounded in docs

I know everything about remnote-server. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

  • ✓README presentThe repository ships documentation.
  • !Scoped permissionsDoesn't declare a permission scope. Assume it can do anything its process can.

4 checks have not been run yet.

README

RemNote MCP Server

License CI npm version codecov

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

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). The same npm package also provides remnote-cli, a command-line MCP client for local scripts and coding harnesses. 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.

Demo

See AI agent examples in action with RemNote: View Demo →

Two-Component Architecture

This system consists of two separate runtime 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 package that provides the remnote-mcp-server executable for MCP clients and the remnote-cli executable for command-line workflows

The remnote-cli command is not a second server. It calls the MCP endpoint exposed by remnote-mcp-server.

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
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-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. Cloud-based services like Claude Desktop and 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

The package installs both commands:

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

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.14.0 listening { wsPort: 3002, httpPort: 3001 }

Keep this terminal running.

4. Configure Your AI Client

Documentation

Getting Started

Usage

Help & Advanced

Development

Available MCP Tools

Tool Description
remnote_create_note Create notes, markdown trees, or flashcards with title, content, parent, and tags
remnote_search Search knowledge base with full-text search and parent-context metadata; tags remain optional and SDK-limited
remnote_search_by_tag Search by tag with ancestor-context resolution
remnote_read_note Read note by ID with metadata and markdown or structured content; readable tags remain SDK-limited
remnote_update_note Update title, append/replace content, or modify tags
remnote_append_journal Append hierarchical content to today's daily document
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.

See the Tools Reference for detailed usage and examples.

Supported AI Clients

  • Claude Code CLI - Local terminal-based agent
  • Claude Desktop / Cowork - Remote connector clients (require remote access)
  • Accomplish - Task-based MCP client (formerly Openwork)
  • Any MCP client supporting Streamable HTTP transport
  • 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.

See CLI Options 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 both remnote-mcp-server and remnote-cli:
./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 canonical workflow for updating and running shared live integration coverage, see the Integration Testing Guide.

Related Projects

License

MIT

Links

README copy captured when this server was indexed; it may lag the repository. The original is authoritative.

Questions

About remnote-server

How do I install remnote-server?

Run npx remnote-mcp-server, then add the server to your MCP client's configuration.

Is remnote-server safe to use with an AI agent?

Its trust score is 42 out of 100 (fair). It passes 1 of the 2 static security checks run so far; the failures are listed above. It has no ConduID identity yet, so agent calls to it are not receipted.

Is remnote-server still maintained?

Yes — the last commit was yesterday. The repository has 30 stars and 0 forks.