SiYuan MCP 安装总结

1. 背景

之前已为 Claude Code 配置了 MiniMax MCP，今天再配置思源笔记（SiYuan）MCP，实现 AI 与思源笔记的联动。

2. MCP 简介

MCP（Model Context Protocol） ：模型上下文协议，是一种让 AI 客户端（如 Claude Code）能调用外部工具的标准协议。MCP Server 本质上是一个符合 MCP 协议的可执行程序，客户端通过 stdio 与其通信。

3. 思源笔记 MCP

项目地址：xgq18237/siyuan_mcp_server，npm 包名：siyuan-mcp，提供 49 个 API 接口。

4. 安装步骤

4.1 获取 API Token

思源笔记 → 设置​ → 关于​ → API令牌，生成或复制令牌。

4.2 配置 Claude Code

编辑 ~/.claude.json​，在 mcpServers 中添加：

{
  "siyuan-mcp": {
    "command": "npx",
    "args": ["-y", "siyuan-mcp@latest"],
    "env": {
      "SIYUAN_HOST": "192.168.12.110",
      "SIYUAN_PORT": "6806",
      "SIYUAN_TOKEN": "你的API令牌"
    }
  }
}

5. 工作原理

​npx siyuan-mcp@latest → npx 从 npmjs.com 下载 siyuan-mcp 包 → 运行包中的 MCP Server 程序 → Claude Code 通过 stdio 与其通信 → 调用思源笔记 API。

GitHub 仓库名与 npm 包名可以不同，仓库是源代码，包是发布到 npm registry 的分发形式。

6. 可用工具（部分）

• ​list_notebooks - 列出所有笔记本
• ​create_doc - 创建文档
• ​sql_query - 执行 SQL 查询
• ​get_file​ / put_file - 文件读写
• ​push_msg​ / push_err_msg - 推送消息

完整列表见 GitHub README。

7. 验证

重启 Claude Code 后，运行 /mcp​ 查看是否成功加载 siyuan-mcp。

8. 遇到的问题

• 连接失败：检查思源笔记是否运行、IP:Port 是否正确、API Token 是否有效
• npx 找不到：确保 Node.js 已安装，npx 在 PATH 中