Simplenote MCP

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 opens Simplenote's login page in your browser. After you log in, the page shows a one-time code; paste it into setup, then choose 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 opens https://app.simplenote.com/login/?source=mcp in your browser and also prints the link. It doesn't try to open a browser over SSH or on Linux without a display, so you can open the link on any machine. Log in with any method Simplenote supports (email code, password, or WordPress.com). Instead of logging you in to the web app, the page shows a code like you@example.com:ABC123; paste the whole string at the setup prompt. Setup then asks whether to enable write mode. On success, it writes config.json and stores the token with mode 0600 in auth.json.

Codes are single-use and expire 5 minutes after they're shown. If setup reports that the code was rejected, run setup again to get a fresh one.

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

No token expiry has been observed in normal use; treat any 401 from the Simperium API as "remove the old token and run setup again." There is no automatic refresh: getting a new token always requires logging in through the browser. Redeeming the code is rate-limited; if setup hits the limit, it waits and retries. Don't script repeated login attempts.

Configuration

Clients with a CLI (Claude Code, Codex) can register the server with one command — see below. Everything else is JSON: all MCP clients converge on the same { command, args, env } shape, and only the config file location and the top-level key (mcpServers vs. servers vs. context_servers) differ between them.

Claude Code

Recommended:

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

Or edit ~/.claude.json / project .mcp.json with the same JSON shape as Claude Desktop below.

Codex

Recommended:

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

Or edit ~/.codex/config.toml directly:

[mcp_servers.simplenote]

command = "npx" args = ["-y", "@automattic/simplenote-mcp"]

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{

"mcpServers": { "simplenote": { "command": "npx", "args": ["-y", "@automattic/simplenote-mcp"] } } }

Run npx -y @automattic/simplenote-mcp setup once in a terminal before starting the client.

Restart Claude Desktop to pick up config changes. See Windows notes below for Windows-specific quirks.

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project). Same JSON shape as Claude Desktop.

VS Code (GitHub Copilot)

User config via Command Palette → "MCP: Open User Configuration", or per-project .vscode/mcp.json. Note: VS Code uses servers at the top level, not mcpServers.

{

"servers": { "simplenote": { "command": "npx", "args": ["-y", "@automattic/simplenote-mcp"] } } }

Zed

In Zed's settings.json:

{

"context_servers": { "simplenote": { "command": { "path": "npx", "args": ["-y", "@automattic/simplenote-mcp"] } } } }

Zed uses a different schema — context_servers with a nested command object.

Cline

Open the Cline MCP Servers panel → edit cline_mcp_settings.json. Same JSON shape as Claude Desktop (mcpServers top-level key).

Windsurf

~/.codeium/windsurf/mcp_config.json. Same JSON shape as Claude Desktop.

Custom store path (macOS)

If your local Simplenote data is not at the default path:

1. Open Finder, press Cmd+Shift+G, paste ~/Library/Group Containers/
2. Look for a folder starting with com.automattic.SimplenoteMac (typically prefixed like PZYM8XX95Q.)
3. Navigate to Data/Simplenote.storedata

Then pass --path:

{

"mcpServers": { "simplenote": { "command": "npx", "args": [ "-y", "@automattic/simplenote-mcp", "--path", "/path/to/Simplenote.storedata" ] } } }

--path always forces the native provider, even if a token is configured.

Other flags

• -h, --help — print usage and exit.
• -V, --version — print version and exit.

Unknown flags and unexpected positional arguments are rejected. This prevents silent typos like --paht from being ignored and falling back to whatever provider is configured in config.json.

Telemetry

Simplenote MCP sends anonymous usage events to Automattic. A random UUID is stored in telemetry.json under the same config directory as config.json and is sent as _ui with _ut=simplenote:local_uuid.

Tracked events are limited to setup choices (type, OS family, write mode, and auth method for API setup) and tool calls (tool, provider, success/failure). Note IDs, note content, tags, search queries, Simplenote account details, and tokens are never sent.

To opt out for one run, set:

SIMPLENOTE_MCP_DISABLE_TELEMETRY=1 npx -y @automattic/simplenote-mcp

To persistently opt out:

npx @automattic/simplenote-mcp disable-telemetry

When running from a local checkout after building, node server.js disable-telemetry works too.

Provider resolution

The server chooses a data source from config.json, except when --path is provided:

1. --path — forces the native macOS provider against the given store file
2. source: "local" — uses the default macOS Simplenote store, read-only
3. source: "api" plus auth.json or SIMPLENOTE_TOKEN — uses the Simperium API provider
4. Missing or malformed config — exits with an actionable simplenote-mcp setup message

Run simplenote-mcp setup to create or replace the config. A token alone is not enough to select the API provider.

Available tools

The basic read tools are available for whichever provider is configured. Native macOS mode is local and read-only. Write tools and version-history tools require the Simperium API provider; in the current server they are exposed when API write mode is enabled.

list_tags

List all tags in your Simplenote account.

Parameters: None

Returns: Array of {name, index} sorted by index

list_notes

List recent notes, optionally filtered by tag.

Parameters:

• tag (string, optional) — filter by tag name
• limit (number, optional, default: 20, max: 100) — max notes to return
• include_deleted (boolean, optional, default: false) — include trashed notes

Returns: Array of {id, title, tags, pinned, modified, deleted} sorted by pinned status then modification date

search_notes

Search notes by content, title, or tags.

Parameters:

• query (string, required) — search term (case-insensitive)
• limit (number, optional, default: 10, max: 100) — max results
• include_deleted (boolean, optional, default: false) — include deleted notes

Returns: Array of {id, title, tags, snippet, modified, deleted}

get_note

Get the full content of a specific note.

Parameters:

• id (string, required) — note ID (simperiumkey)
• include_deleted (boolean, optional, default: false) — allow retrieving deleted notes

Returns: {id, content, tags, pinned, markdown, deleted, created, modified}

create_note

Create a new note. Write tool — requires write mode enabled in simplenote-mcp setup and the Simperium API provider.

Parameters:

• content (string, required) — note content (first line becomes title)
• tags (array of strings, optional) — tags to attach
• markdown (boolean, optional, default: true) — enable markdown rendering
• pinned (boolean, optional, default: false) — pin to top of list

Returns: {success, id, version, title}

update_note

Update an existing note. Write tool — requires write mode and the Simperium API provider.

Important: content and tags replace the existing values in full. When changing only part of a note, call get_note first and pass the merged content back. A partial value will erase the rest.

Parameters:

• id (string, required) — note ID
• content (string, optional) — new note content
• tags (array of strings, optional) — replace the tag list (provide the full list)
• markdown (boolean, optional) — enable/disable markdown rendering
• pinned (boolean, optional) — pin/unpin

At least one of content, tags, markdown, or pinned must b