MCP Server (stdio) for Claude Desktop / Code

Status: shipped in Phase 0.9 · Issue: #9

A standalone stdio MCP server bundled inside the .vsix exposes your global Mark It Down notes to Claude Desktop and Claude Code. Install with one click; the server reads from the same on-disk store the Notes sidebar writes to.

At a glance

Server binary	out/mcp/server.js (bundled by esbuild from src/mcp/server.ts, ~1.1MB CJS, Node 18+)
Transport	stdio (@modelcontextprotocol/sdk's StdioServerTransport)
CLI args	--notes-dir <path> — required; the directory containing _mcp-index.json and the <id>.md files
Install	Mark It Down: Install MCP for Claude Desktop / Code command
Scope	Global notes only (workspace notes are per-VSCode-window and not addressable from outside)
Tools	list_notes, get_note, create_note, update_note, delete_note
Deferred to v1+	get_active_markdown, list_open_md (registered as stubs that return a clear "requires extension IPC" error)

How it works

The extension owns the canonical state (workspaceState/globalState index + <id>.md files). On every change to the global-scope notes, it writes a _mcp-index.json snapshot under globalStorage/notes/ that the MCP server reads.

The MCP server runs as a separate Node process spawned by Claude Desktop/Code per the standard MCP launch model. It does not require VSCode to be running — but mutations made via MCP tools while the extension is also running will only be visible in the Notes sidebar after a tree refresh (the extension watches the index file via the standard NotesStore change events; cross-process change detection is on the roadmap).

Install

Run Mark It Down: Install MCP for Claude Desktop / Code from the command palette. You'll get a Quick Pick:

Target	Where the config lands
Claude Desktop	macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%/Claude/... · Linux ~/.config/Claude/...
Claude Code (project-level)	<workspace>/.mcp.json (or ~/.mcp.json if no folder is open)

Pick one, and the install command:

1. Reads (or creates) the target JSON config
2. Adds an mcpServers["mark-it-down"] entry pointing at the bundled server with the right --notes-dir for your VSCode global storage
3. Offers Reveal Config to inspect the result

The entry looks like:

After installing, restart Claude Desktop or Claude Code so it picks up the new server. From the next session, you'll have the Mark It Down tools available.

There's a companion command Mark It Down: Show MCP Server Path (copy to clipboard) that just copies the absolute path to the bundled server.js for users who want to wire it into other MCP clients manually.

Tools

All tools take JSON inputs and return text content blocks. The server is registered as mark-it-down v0.9.0.

list_notes(category?)

List global notes. Optionally filter by category.

Returns a JSON array of note metadata: { id, title, category, scope, createdAt, updatedAt, filename }.

get_note(id)

Read one note by id. Returns metadata + full markdown content as two text blocks.

create_note(title, category, content?)

Create a new global note. content defaults to # <title>\n\n.

Returns the created note's metadata.

update_note(id, ...patch)

Patch any of title, category, content. Bumps updatedAt.

delete_note(id)

Permanently delete a note. No soft-delete.

get_active_markdown ✓ (v0.9.1)

Returns the markdown currently open in the active VSCode editor. Requires --ipc-sock to be set when the MCP server launches (the install command sets it automatically). Returns null when no markdown editor is active. Returns an isError result if the IPC channel can't be reached (extension not running, stale socket).

Response shape:

list_open_md ✓ (v0.9.1)

Lists every open .md / .mdx document in the running VSCode. Same IPC requirements as above. Returns an empty array when no markdown is open.

Response shape:

How the IPC channel works (v0.9.1+)

On extension activation, McpIpcServer listens on a Unix-domain socket (POSIX) or named pipe (Windows). Endpoint:

OS	Endpoint
macOS / Linux	${globalStorageUri}/mid-mcp.sock
Windows	\\.\pipe\mark-it-down-<hash-of-globalStorage>

The MCP server spawns with --ipc-sock <endpoint> (passed automatically by the Install MCP for Claude Desktop / Code command). When get_active_markdown or list_open_md is called, it connects, sends a newline-delimited JSON request, awaits the matching id response, then closes the socket. One connection per call — cheap at MCP's volume, no pool / reconnect logic needed.

If the extension isn't running (or --ipc-sock was omitted), both tools return a clear error explaining the requirement.

What lives where

Path	Purpose	Owner
out/mcp/server.js	Bundled MCP server entry	extension build
src/mcp/server.ts	MCP server source (registers tools, wires StdioTransport)	source
src/mcp/notesAdapter.ts	File-system notes I/O (read index + content, mutate both)	source
src/mcp/installCommand.ts	VSCode commands that write the MCP entry to client configs	source
globalStorage/.../notes/_mcp-index.json	Snapshot of global note metadata, written by the extension	extension runtime
globalStorage/.../notes/<id>.md	Each note's markdown content	extension + MCP both write

Edge cases & limitations

• MCP server can't see workspace-scope notes. Workspace notes live in <workspaceStorage>/notes/ per workspace; the MCP server has no way to enumerate VSCode workspaces. Workspace notes are exposed through the warehouse repo instead.
• Concurrent writes. If the MCP server creates/updates a note while the extension is mid-save on a different note, they race on the index file. The extension's writeMcpIndexSnapshot() and the MCP server's writeIndex both rewrite the whole file; last writer wins. Real cross-process locking is a future addition.
• Stale index after MCP-side mutations. When the MCP server creates/updates/deletes notes, the extension does NOT automatically refresh its sidebar — its in-memory index stays current with workspaceState/globalState, not the on-disk _mcp-index.json. After running MCP-side mutations, click the Notes sidebar Refresh button to re-read from disk. Auto-watching the index file from inside the extension is a follow-up.
• get_active_markdown / list_open_md are stubs that return a clear error. Don't bind workflows to them in v0.9.
• --notes-dir must exist. First time: install via the command (which uses the absolute global-storage path) OR create the directory manually.
• Restart required. Claude Desktop / Code only re-reads MCP configs at startup. After install, restart the client.

Files of interest

• src/mcp/server.ts — server entry, McpServer + 7 tool registrations
• src/mcp/notesAdapter.ts — pure-Node fs adapter (listNotes, getNote, createNote, updateNote, deleteNote)
• src/mcp/installCommand.ts — markItDown.mcp.install (Quick Pick + JSON-merge into client config), markItDown.mcp.revealServer
• src/notes/notesStore.ts — writeMcpIndexSnapshot() writes the snapshot the MCP server reads
• src/extension.ts — wires the install commands and the snapshot-on-change listener
• package.json — compile:mcp build step (esbuild → CJS Node18); markItDown.mcp.install + markItDown.mcp.revealServer command registrations