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

Tool	Description	Gating
list_notes	Walk the vault and return metadata (path, name, title, mtime, size, summary). Defaults to 100 notes, sorted newest-first.	always
read_note	Full content of one note, plus parsed front matter, headings, tags, and outbound [[wikilinks]].	always
search	Substring or regex search. Uses ripgrep when on PATH, otherwise a Rust regex walk. Caps at 200 hits with 3-line context.	always
get_backlinks	Every place that wikilinks the named note (case-insensitive on the file stem).	always
list_tags	Aggregated tag counts across the vault — body #tag plus front-matter tags:.	always
get_outline	Heading outline of a single note (level 1-6, text, line).	always
list_tasks	Every - [ ] / - [x] checkbox in the vault, with file, line and done state; done filters.	always
autogit_log	Commit history of one note from the AutoGit repo, newest first.	always
autogit_diff	Unified diff of one note between two AutoGit commits.	always
sync_status	GitHub-sync state from .solomd/sync.json (remote, branch, encryption).	always
share_url	Public solomd.app/share URL for a note in a linked repo.	always
read_agent_trace	Steps of one agent run from .solomd/agent-runs/<run_id>/trace.jsonl; an unknown run id is an error.	always
write_note	Create a .md / .markdown / .txt note (missing folders inside the workspace are created). Replaces an existing note only with allow_overwrite: true.	--allow-write
append_to_note	Append text to an existing note (newline-safe).	--allow-write
autogit_rollback	Restore a note's content from an AutoGit commit.	--allow-write
export_note	Export a note to html / md / txt / docx. output_path may be outside the workspace (its folder must exist); an existing file is replaced only with overwrite: true.	--allow-write, and listed only when the Node backend is found (below)

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.