npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

remnote-mcp-server

v0.15.0

Published

MCP server bridge for RemNote knowledge base

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

robert-viirobert-vii

Keywords

mcpremnotemodel-context-protocolknowledge-basenote-takingaiassistantwebsocketbridge

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.

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 (for example, 0.15.x with 0.15.x). 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.

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 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 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

Documentation

Getting Started

Usage

Help & Advanced

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

License

MIT

Links