siyuan-note-mcp

把 思源笔记（SiYuan）接入任何 MCP 客户端——Claude Desktop、Cursor、Cline、DeepSeek Harness 等。装上后，你的 agent 就能直接搜索、读取和写入思源里的笔记本、文档与内容块。

特性

• 13 个工具覆盖日常读写：笔记本、文档、内容块、全文搜索、SQL 查询

• 零配置起步 — 默认连本机 http://127.0.0.1:6806，本地思源免 token

• 按 ID 或路径寻址 — 文档既可用 ID，也可用 /笔记/我的文档 这样的人类可读路径

• 只读 SQL 保护 — sql_query 只放行 SELECT/WITH/EXPLAIN

• 错误可自愈 — 内核报错原文回传给模型，附带修正建议

Related MCP server: SiYuan MCP Server

安装

需要 Node.js ≥ 20，且思源笔记正在运行。

git clone https://github.com/Miles1994/siyuan-mcp.git
cd siyuan-mcp
npm install && npm run build

尚未发布到 npm。必须执行 npm run build——仓库不包含 lib/ 构建产物，不构建就没有可运行的文件。 发布后可直接用 npx -y siyuan-note-mcp 替代。注意：npm 上已有的 siyuan-mcp 是另一个项目，本包名是 siyuan-note-mcp。

客户端配置

把下面这段加进 MCP 客户端配置，args 换成你的实际路径（Windows 下用正斜杠 /）：

{
  "mcpServers": {
    "siyuan": {
      "command": "node",
      "args": ["/path/to/siyuan-mcp/lib/cli.js"]
    }
  }
}

连接远程或开启鉴权的内核时，再加环境变量：

{
  "mcpServers": {
    "siyuan": {
      "command": "node",
      "args": ["/path/to/siyuan-mcp/lib/cli.js"],
      "env": {
        "SIYUAN_API_URL": "http://192.168.1.5:6806",
        "SIYUAN_TOKEN": "你的 API token"
      }
    }
  }
}

API token 在思源的 设置 → 关于 里查看。

配置项

思源默认只监听 127.0.0.1 且不校验 token。把内核暴露到局域网时请务必在设置里开启鉴权并配置 SIYUAN_TOKEN。

工具一览

设计说明

为什么 sql_query 只能读

思源的 /api/query/sql 虽然文档上叫查询接口，但内核实际允许通过它执行写入——实测 3.8.4：DELETE FROM blocks WHERE 1=0 正常返回 code: 0。

原样暴露的话，模型就能绕过所有块级写工具直接改索引。因此本项目在本地拦截写操作，且用词法分析而非关键字正则：注释和字符串字面量里的关键字会被忽略，所以 WHERE content = 'please delete this' 能过，SELECT 1; DROP TABLE blocks 会被拒。

索引延迟

思源的 SQL 索引和全文索引是异步更新的，实测写入后约 2 秒才可见；而文档路径解析走文档树接口（getIDsByHPath），立即可见。所以：

• 刚创建的文档，用路径或 ID 读取立刻可用

• list_documents、search_notes、sql_query 这类走索引的结果，可能要等一两秒

这是内核的最终一致性设计，不是 bug。测试中的对应处理见 tests/e2e.spec.ts 的 waitFor。

DeepSeek Harness (DSH)

DSH 通过 @deepseek-ai/dsh-mcp-client 挂载外部服务器，配置在 ~/.dsh/profiles/<profile>/cordis.patch.yml。

装了 dsh-skill-mcp-panel 的话，该文件中的 MCP 区块由它托管，不要手改区块内内容（会被覆盖），改用它的 CLI：

dsh-panel mcp add --name siyuan --stdio --command node \
  --args "/path/to/siyuan-mcp/lib/cli.js" --profile web

dsh-panel mcp test siyuan --profile web     # 验证连通性
dsh-panel mcp list --profile web            # 查看启用状态

否则手动插入这段（cordis.patch.yml 顶层是一个数组）：

- insert:
    - id: mcp-siyuan
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: siyuan
        transport: stdio
        command: node
        args:
          - /path/to/siyuan-mcp/lib/cli.js
        env:
          SIYUAN_API_URL: http://127.0.0.1:6806
        cwd: ""

工具会以 mcp__siyuan__search_notes、mcp__siyuan__get_document 这样的名字出现。

args 里的路径不要加引号。stdio 直接传参数数组、不经过 shell，写成 '"/path/to/cli.js"' 会把引号当成文件名的一部分，spawn 时报 ENOENT。

开发

npm run build      # 构建到 lib/
npm test           # 单元测试
npm run typecheck  # 类型检查

端到端测试会直接连你本机的思源，创建并删除一个临时文档；检测不到内核时自动跳过：

npx vitest run tests/e2e.spec.ts

许可

MIT