SoloMD

solomd-mcp — SoloMD 知识库的 Model Context Protocol 服务

solomd-mcp 让 Claude Code、Codex CLI、Cursor、Continue 和其他任何 MCP 客户端都能读取（并可选择编辑）SoloMD Markdown 笔记文件夹。你的 知识库会成为助手可以调用的一等工具。

它是一个独立的 Rust 二进制文件。桌面应用会附带一份副本（在 macOS 上：/Applications/SoloMD.app/Contents/MacOS/solomd-mcp），但不会自行 运行它；只有 MCP 客户端启动它时才会运行。它报告的版本与应用相同（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)

多个工作区（v4.0+）

每个知识库传入一次 --workspace。每个值可以是纯路径（别名默认为路径的最后 一个组成部分），也可以是 <alias>=<path>：

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

第一个工作区是默认工作区——未显式传入 workspace 参数的工具调用都会指向它。现有的单个 --workspace 客户端 仍可照常使用。要定位到非默认工作区的工具，只需额外传入一个 workspace 参数：

// 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" } }

每个工作区的 AutoGit 历史记录（autogit_log、autogit_diff、 autogit_rollback）彼此独立——每次调用时都会按需打开各自工作区的 .git 仓库。

提供的工具

工具	描述	限制条件
list_notes	遍历知识库并返回元数据（路径、名称、标题、修改时间、大小、摘要）。默认返回 100 条笔记，按最新优先排序。	始终可用
read_note	返回一条笔记的完整内容，以及解析后的 front matter、标题、标签和出站 [[wikilinks]]。	始终可用
search	子字符串或正则表达式搜索。若 PATH 中有 ripgrep，则使用它；否则使用 Rust 正则表达式遍历。最多返回 200 条命中结果，并附带 3 行上下文。	始终可用
get_backlinks	返回所有链接到指定笔记的位置（文件名不区分大小写）。	始终可用
list_tags	汇总整个知识库中的标签数量，包括正文中的 #tag 和 front matter 中的 tags:。	始终可用
get_outline	返回单条笔记的标题大纲（级别 1-6、文本、行号）。	始终可用
list_tasks	返回整个知识库中的所有 - [ ] / - [x] 复选框及其文件、行号和完成状态；可通过 done 进行筛选。	始终可用
autogit_log	返回 AutoGit 仓库中单条笔记的提交历史，按最新优先排序。	始终可用
autogit_diff	返回 AutoGit 中单条笔记两个提交之间的统一差异。	始终可用
sync_status	返回 .solomd/sync.json 中的 GitHub 同步状态（远程服务、分支、加密）。	始终可用
share_url	返回已关联仓库中笔记的公开 solomd.app/share URL。	始终可用
read_agent_trace	返回 .solomd/agent-runs/<run_id>/trace.jsonl 中某次 Agent 运行的步骤；未知的 run id 会报错。	始终可用
write_note	创建 .md / .markdown / .txt 笔记（会创建工作区内缺失的文件夹）。仅当设置 allow_overwrite: true 时才会替换现有笔记。	--allow-write
append_to_note	向现有笔记追加文本（安全处理换行）。	--allow-write
autogit_rollback	从 AutoGit 提交中恢复笔记内容。	--allow-write
export_note	将笔记导出为 html / md / txt / docx。output_path 可以位于工作区之外（其文件夹必须存在）；仅当设置 overwrite: true 时才会替换现有文件。	--allow-write，且仅在找到 Node 后才会列出（见下文）

总计 16 个工具。默认只读。写入工具也会通过 MCP tools/list 响应提供，以便客户端显示；但在启用前调用会失败，并显示明确的“使用 --allow-write 重启”提示。

所有行号（get_outline、get_backlinks、read_note 的标题和 wikilinks、list_tasks、search）都对应磁盘上文件中的 1 起始行号，包含 front matter，因此各工具之间以及与编辑器中的行号保持一致。search 的列号按字符计数，而不是按字节计数。

export_note 需要 Node.js 和 SoloMD 源代码检出副本。 它会运行 app/scripts/solomd-export.mjs（与 solomd export 使用相同的引擎），并使用应用的 node_modules。已安装的应用不包含这些内容，因此仅当 node 位于 PATH 中且找到该脚本时才会列出此工具：可通过 SOLOMD_EXPORT_SCRIPT=/path/to/solomd/app/scripts/solomd-export.mjs 指定，或者在二进制文件或工作目录位于已在 app/ 中运行过 pnpm install 的检出副本内时自动找到。

安装

单行安装程序（macOS / Linux）

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

此命令会从最新的 GitHub 版本下载适用于你平台的二进制文件，并将其放入 /usr/local/bin/solomd-mcp（如果系统路径不可写，则放入 ~/.local/bin/solomd-mcp）。

Cargo

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

手动安装

从 github.com/zhitongblog/solomd/releases 下载适用的压缩包，解压 solomd-mcp，并将其放入 PATH。

配置连接

Claude Code

最简单的方法是使用 CLI——它会为你写入用户级配置（~/.claude.json）：

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

若要将服务限定到一个项目，则在项目根目录中放置 .mcp.json：

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

多工作区配置（一台 MCP 服务，多个知识库）：

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

启用写入功能：

{
  "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 / 通用

任何通过 stdio 使用 MCP 的客户端都可以使用。将其 command 指向 solomd-mcp，并传入 --workspace <path>。solomd CLI （scripts/install-cli.sh）可以代劳：solomd mcp install 会将条目写入它找到的每个 AI 客户端，solomd mcp-config 会打印该条目。

托管客户端（Streamable HTTP）

对于无法启动本地二进制文件的客户端（Smithery、Claude.ai 远程 MCP、ChatGPT 连接器），请运行 HTTP 传输：

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

默认情况下，它会绑定到 loopback，因此在更改 --bind 之前，机器外部无法访问它。使用 --auth-token（或 SOLOMD_MCP_TOKEN）时，每个请求都必须发送 Authorization: Bearer <token>；如果未设置令牌，任何能访问该地址的对象都可以访问此端点。

CLI 参考

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.

设置 SOLOMD_MCP_LOG=trace（或任何 tracing-subscriber 过滤表达式）以进行更精细的控制。

安全性

• 每个输入路径都会先规范化，并验证其位于工作区内，然后才进行任何读写。.. 路径段以及指向工作区外部的绝对路径都会被拒绝。唯一可能在工作区外写入的工具是 export_note，且必须使用 --allow-write；它不会在那里创建文件夹，也不会替换现有文件，除非调用传入 overwrite: true。
• 此处不会使用 SoloMD 桌面应用的监视器 / 索引——这是一个无状态的按次调用服务，会按需遍历文件系统。
• list_notes 只读取每个文件开头的 8 KB（足以获取标题和摘要），因此即使知识库中有数千篇大型笔记，枚举开销也很低。只有调用 read_note 时才会加载完整文件内容。

验证

# 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

你应该会看到列出的 16 个工具（如果 export_note 的 Node 后端不可用，则为 15 个）。

许可证

MIT——与 SoloMD 相同。