SoloMD

solomd-mcp — Model Context Protocol server for SoloMD vaults

solomd-mcp lets Claude Code, Codex CLI, Cursor, Continue, and any other MCP client read (and optionally edit) a SoloMD Markdown notes folder. Your vault becomes a first-class tool the assistant can call.

It is a standalone Rust binary. The desktop app bundles a copy (on macOS: /Applications/SoloMD.app/Contents/MacOS/solomd-mcp) but never runs it itself; it only runs when an MCP client starts it. It reports the same version as the app (solomd-mcp --version).

solomd-mcp --workspace /Users/me/Documents/Notes# stdin / stdout: JSON-RPC 2.0 (stdio transport, the default)# stderr:        human logs (use --verbose for debug)

Multiple workspaces (v4.0+)

Pass --workspace once per vault. Each value is either a bare path (alias defaults to the path's last component) or <alias>=<path>:

solomd-mcp \  --workspace work=/Users/me/Documents/Work \  --workspace home=/Users/me/Documents/Home

The first workspace is the default — tool calls without an explicit workspace argument resolve to it. Existing single---workspace clients keep working unchanged. Tools that want to target a non-default workspace pass an extra workspace argument:

// Default (first registered) workspace:{ "name": "list_notes", "arguments": {} }
// Explicit alias:{ "name": "list_notes", "arguments": { "workspace": "home" } }
// Or by absolute path (must match a registered workspace):{ "name": "list_notes", "arguments": { "workspace": "/Users/me/Documents/Home" } }

Each workspace's AutoGit history (autogit_log, autogit_diff, autogit_rollback) is independent — the per-workspace .git repo is opened on demand for each call.

Tools exposed

That is 16 tools. Read-only by default. Write tools are also offered through the MCP tools/list response so clients can show them, but invocations fail with a clear "restart with --allow-write" message until you opt in.

Every line number (get_outline, get_backlinks, read_note headings and wikilinks, list_tasks, search) is a 1-based line in the file as it sits on disk, front matter included, so the tools agree with each other and with an editor. search columns count characters, not bytes.

export_note needs Node.js and a SoloMD source checkout. It runs app/scripts/solomd-export.mjs (the same engine as solomd export) with the app's node_modules. The installed app ships neither, so the tool is only listed when node is on PATH and the script is found: via SOLOMD_EXPORT_SCRIPT=/path/to/solomd/app/scripts/solomd-export.mjs, or automatically when the binary or the working directory is inside a checkout where pnpm install has been run in app/.

Install

One-line installer (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/zhitongblog/solomd/main/scripts/install-mcp.sh | bash

This downloads the right binary for your platform from the latest GitHub release and drops it into /usr/local/bin/solomd-mcp (falling back to ~/.local/bin/solomd-mcp if the system path is not writable).

Cargo

cargo install --git https://github.com/zhitongblog/solomd solomd-mcp

Manual

Grab the right archive from github.com/zhitongblog/solomd/releases, extract solomd-mcp, and put it on your PATH.

Wire it up

Claude Code

Easiest route is the CLI — it writes the user-scope config (~/.claude.json) for you:

claude mcp add --scope user solomd-vault -- \  solomd-mcp --workspace /Users/me/Documents/Notes

To scope the server to one project instead, drop an .mcp.json in the project root:

{  "mcpServers": {    "solomd-vault": {      "command": "solomd-mcp",      "args": ["--workspace", "/Users/me/Documents/Notes"]    }  }}

Multi-workspace profile (one MCP server, several vaults):

{  "mcpServers": {    "solomd-vaults": {      "command": "solomd-mcp",      "args": [        "--workspace", "work=/Users/me/Documents/Work",        "--workspace", "home=/Users/me/Documents/Home"      ]    }  }}

To enable writes:

{  "mcpServers": {    "solomd-vault": {      "command": "solomd-mcp",      "args": ["--workspace", "/Users/me/Documents/Notes", "--allow-write"]    }  }}

Codex CLI

~/.codex/config.toml:

[mcp_servers.solomd-vault]command = "solomd-mcp"args = ["--workspace", "/Users/me/Documents/Notes"]

Cursor / Continue / generic

Anything that speaks MCP over stdio works. Point its command at solomd-mcp and pass --workspace <path>. The solomd CLI (scripts/install-cli.sh) can do this for you: solomd mcp install writes the entry into every AI client it finds, solomd mcp-config prints it.

Hosted clients (Streamable HTTP)

For clients that can't spawn a local binary (Smithery, Claude.ai remote MCP, ChatGPT connectors), run the HTTP transport:

solomd-mcp --workspace /Users/me/Documents/Notes \  --transport http --bind 127.0.0.1:8765 --auth-token "$TOKEN"

It binds to loopback by default, so nothing outside the machine can reach it until you change --bind. With --auth-token (or SOLOMD_MCP_TOKEN) every request must send Authorization: Bearer <token>; without one the endpoint is open to anything that can reach the address.

CLI reference

solomd-mcp [OPTIONS] --workspace <ALIAS=DIR | DIR>...
  --workspace <ALIAS=DIR | DIR>                      Path to a notes folder. Required. Canonicalised.                      Repeat for multi-workspace mode. Form: `<alias>=<path>`                      or just `<path>` (alias defaults to the path's last                      component). The first workspace is the default — tool                      calls without an explicit `workspace` argument resolve                      to it (back-compat for single-workspace clients).  --allow-write       Enable write_note + append_to_note + autogit_rollback                      + export_note. Off by default.  --transport <stdio|http>                      stdio (default) or Streamable HTTP.  --bind <ADDR>       HTTP listen address (default 127.0.0.1:8765).  --auth-token <TOKEN>                      HTTP bearer token [env: SOLOMD_MCP_TOKEN].  -v, --verbose       Debug-level stderr logs.  -V, --version       Print version.  -h, --help          Print help.

Set SOLOMD_MCP_LOG=trace (or any tracing-subscriber filter expression) for finer-grained control.

Safety

• Every input path is canonicalised and verified to live inside the workspace before any read/write. Both .. segments and absolute paths outside the workspace are rejected. The one tool that may write outside the workspace is export_note, and only with --allow-write; it never creates folders there and never replaces an existing file unless the call passes overwrite: true.
• The watcher / index from the SoloMD desktop app is not used here — this is a stateless per-invocation server that walks the filesystem lazily.
• list_notes reads only an 8 KB prefix of each file (enough for title + summary), so even a vault with thousands of large notes is cheap to enumerate. Full file content only loads on read_note.

Verifying

# Roundtrip handshake: initialize → tools/list.{  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"smoketest","version":"0"}}}'  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'  sleep 1} | solomd-mcp --workspace ~/Documents/Notes

You should see 16 tools listed (15 if export_note's Node backend isn't available).

License

MIT — same as SoloMD.