Simplenote MCP server

simplenote-mcp

An MCP (Model Context Protocol) server that gives any MCP-compatible AI tool access to your Simplenote data — read by default, with opt-in write tools (create, update, trash, restore, revert) when you run simplenote-mcp setup with write mode enabled.

On macOS, it can read directly from the local Simplenote desktop app's Core Data store — fully offline, no auth. On Linux and Windows (and on macOS without the desktop app), it talks to the Simperium HTTP API after a one-time simplenote-mcp setup.

Works with Claude Desktop, Claude Code, Cursor, VS Code (Copilot), Zed, Cline, Windsurf, and anything else that speaks MCP.

Quick start

Run setup once:

npx -y @automattic/simplenote-mcp setup

On macOS with the Simplenote desktop app installed and synced, setup detects the local database and asks whether to use it. Accepting that option is fully offline and read-only. On Linux, Windows, or macOS without the desktop app, setup prompts for your Simplenote email, sends an auth code, then asks for the code and whether to enable write mode.

Then register the server with your MCP client.

Claude Code:

claude mcp add simplenote -- npx -y @automattic/simplenote-mcp

Codex:

codex mcp add simplenote -- npx -y @automattic/simplenote-mcp

For Claude Desktop, Cursor, VS Code, Zed, Cline, and Windsurf, see Configuration below — these clients are configured by editing a JSON file rather than a CLI command.

Restart the client and ask it to list your tags.

Requirements

• Node.js 22+
• One of:
• macOS: the Simplenote desktop app installed and synced, or
• Any platform: a Simplenote account (you'll run simplenote-mcp setup once)

Install

Most users don't need to install anything manually — npx -y @automattic/simplenote-mcp in the MCP config does it on first use.

If you prefer a global install (faster startup, no cold-cache download on first use):

npm install -g @automattic/simplenote-mcp

Then reference simplenote-mcp directly as the command in your MCP config.

Setup and Authentication

Run setup once to create config.json. Native macOS setup does not require Simplenote authentication; API setup does.

One-time setup

npx -y @automattic/simplenote-mcp setup

If a local macOS Simplenote database is detected, setup offers to use it and writes config.json with source: "local".

Otherwise, setup checks for an existing token in auth.json. If one is already stored, setup reuses it and only asks whether to enable write mode. If no token is stored, setup prompts for your Simplenote email, sends a magic-link email containing a short auth code, prompts for the code, and then asks whether to enable write mode. On success, it writes config.json and stores the token with mode 0600 in auth.json.

config.json and telemetry.json live in the same simplenote-mcp config directory.

To remove the stored token:

npx -y @automattic/simplenote-mcp logout

Headless / CI

Skip auth.json by exporting the token directly:

SIMPLENOTE_TOKEN=<token> npx -y @automattic/simplenote-mcp

The env var bypasses auth.json.

SIMPLENOTE_TOKEN does not bypass config.json; the server still needs config to know whether to use the local store or the API provider. For headless environments, create config.json in the same platform-specific config directory listed above:

{
  "source": "api",
  "writeMode": false
}

Set writeMode to true only when you want write tools exposed.

Token lifetime

Shortened. The full README is on GitHub.