Markpin

@markpin/mcp

MCP server for a Markpin folder. Markpin is a Chrome extension that saves web pages and clips as Markdown files in a folder you own — this server lets an AI client (Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, VS Code, Windsurf, Zed, or any other MCP client) search and read those files, and optionally edit them with your confirmation.

• Read-only by default. Writes need --allow-write and a confirmation dialog for every change.
• Runs locally over stdio. Nothing leaves your computer.
• Watches the folder, so pages you save in the browser show up in the next query without a restart.

Requirements

• Node.js 20.1 or newer (node -v).
• The Markpin Chrome extension with storage set to Local folder or Google Drive. With Google Drive you also need Google Drive for Desktop so the folder exists on disk.

Run

npx -y @markpin/mcp --dir "<your Markpin folder>"

Options:

On success the server logs serving N pages from to stderr. stdout carries the MCP protocol, so all logs go to stderr — that line is the quickest way to check the path.

Find your Markpin folder

The folder must contain a pages/ directory. If it doesn't, the extension hasn't uploaded anything there yet — save a page in Chrome first.

Local folder — the folder you picked in Markpin settings.

• macOS: in Finder, right-click the folder, hold ⌥ Option, choose Copy "…" as Pathname.
• Windows: Shift + right-click the folder, choose Copy as path (remove the surrounding quotes).

Google Drive — Drive for Desktop mirrors your Drive to disk. The Markpin folder sits at the top of *My Drive*, whose name follows your Google account language — My Drive (en), 내 드라이브 (ko), マイドライブ (ja), Mi unidad (es), Meu Drive (pt-BR), Meine Ablage (de), Mon Drive (fr):

• macOS: ~/Library/CloudStorage/GoogleDrive- /My Drive/Markpin
• Windows: G:\My Drive\Markpin (the drive letter can differ — check File Explorer)

The Markpin settings page in Chrome has an MCP setup guide button that fills these paths (and --lang) in for you.

Register the server

Replace with your folder path. Add --allow-write at the end of the arguments if you want the write tools.

Claude Code

claude mcp add -s user markpin -- npx -y @markpin/mcp --dir "<dir>"

-s user registers it for every project; drop the flag to keep it to the current directory only.

Then claude mcp list should show markpin: … - ✓ Connected.

Claude Desktop

Edit the config file (Claude → Settings → Developer → Edit Config):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS:

{

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

Windows (Claude Desktop spawns without a shell, so npx needs cmd /c; escape backslashes in the path):

{

"mcpServers": { "markpin": { "command": "cmd", "args": ["/c", "npx", "-y", "@markpin/mcp", "--dir", "G:\\My Drive\\Markpin"] } } }

Restart Claude Desktop. The hammer/plug icon in the chat box lists the Markpin tools.

Cursor

Add the same JSON to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), then enable the server in Cursor Settings → MCP.

Codex (CLI, IDE extension, ChatGPT desktop)

codex mcp add markpin -- npx -y @markpin/mcp --dir "/path/to/Markpin"

All three share ~/.codex/config.toml. Check with codex mcp list.

Gemini CLI

gemini mcp add markpin npx -- -y @markpin/mcp --dir "/path/to/Markpin"

Server flags go after -- so Gemini doesn't read them as its own options. Saved to ~/.gemini/settings.json; check with gemini mcp list.

VS Code (Copilot agent mode)

.vscode/mcp.json in the project, or the user mcp.json opened by MCP: Open User Configuration. Note the key is servers and stdio needs type:

{

"servers": { "markpin": { "type": "stdio", "command": "npx", "args": ["-y", "@markpin/mcp", "--dir", "/path/to/Markpin"] } } }

Windsurf

Same JSON as Claude Desktop (mcpServers) in ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json), then refresh under Settings → MCP.

Zed

~/.config/zed/settings.json (Windows: %APPDATA%\Zed\settings.json). The key is context_servers, hand-added servers need source: "custom", and the command is nested:

{

"context_servers": { "markpin": { "source": "custom", "command": { "path": "npx", "args": ["-y", "@markpin/mcp", "--dir", "/path/to/Markpin"] } } } }

Any other MCP client

Anything that speaks MCP over stdio works. Paste the same command (npx) and args (-y @markpin/mcp --dir …) into that client's MCP settings. On Windows, clients that spawn without a shell need cmd /c npx … (see the Claude Desktop note above).

File format

Each page is one Markdown file. The frontmatter holds only the human-facing keys (title, url, savedAt, tags, summary, readAt, deletedAt) so note apps such as Obsidian show a clean Properties panel. Everything Markpin needs internally (id, rev, updatedAt, clips with their anchors, bookmark) lives in a one-line JSON block at the very end of the file:

Do not edit that block by hand. Files written before 0.7.0 (markpin: 1 in the frontmatter) are still read; they are rewritten in the new shape the next time anything changes them.

markpin.json (Markdown template)

The extension writes markpin.json at the folder root when you pick a Markdown template or turn on .trash/ in its options. This server reads it on start and on every rescan, and renders the files it writes with the same template (default or obsidian, or a custom template string), so pages saved through MCP look like the ones saved from the browser. Only the body below the frontmatter changes; the frontmatter is always Markpin's own. Moving deleted files to .trash/ is done by the extension, not by this server.

Read-only vs. --allow-write

Without --allow-write the server exposes four read tools and cannot change any file. With it, fourteen write tools are added. Every write passes three gates:

1. The flag. You decided at registration time that writes are allowed at all.
2. Client permission. The tools are marked non-read-only (delete_pages as destructive), so clients such as Claude Code ask before each call.
3. Your confirmation. If the client supports MCP elicitation (Claude Code does), the server shows a dialog describing the exact change — for example *"Add tag frontend to 'React Docs'?"* — and writes only when you accept. The dialog also has a checkbox, *Don't ask again on this connection*: tick it with your confirmation and later writes on that connection (including delete_pages) are applied without the dialog and carry "gate": "trusted"; it resets when the client restarts, and the client's own permission prompts are unaffected. If the client cannot show that dialog, the result carries "gate": "client" so the assistant can tell you that the client's own prompt was the only confirmation.

When one request needs several writes — merging tags, clipping three passages — the assistant is told to use retag or batch so you confirm once with a numbered list instead of once per write.

The confirmation waits up to 10 minutes. A save_page fetch happens only after you accept, so a declined URL is never requested.

Tools

Read (always):

Write (--allow-write):

Every write returns a note and a gate field ("elicitation" when you confirmed in the dialog, "trusted" when you had ticked *Don't ask again on this connection*, "client" when only the client's prompt stood between the assistant and the write). update_tags, retag, set_clip_note, set_summary and set_note also return before/after; the others return the affected page(s). batch returns { results, completed, gate }, where results lists each op in order as { tool, ok: true, result }, { tool, ok: true, skipped: true } or { tool, ok: false, error } (nothing after a failed op), and completed counts the ops that ran and succeeded.

Limits

• Google Drive + new pages. With Google Drive storage the extension can only read files it created itself (drive.file scope), so save_page writes new pages to inbox.jsonl in your Markpin folder and the extension turns them into page files on its next sync. The extension cre