思源接入AI(本地／远程)

前言

之前一直在用思源笔记做知识管理，但随着笔记越来越多，手动检索和整理变得低效。最近发现可以通过 MCP 直接接入思源笔记的 API

让AI帮我查找修改笔记，还能根据基模能力对笔记的优缺进行评价，感觉挺实用，记录一下配置过程

本文分两部分：本地 Cursor IDE 配置，以及远程 Linux 机器（如 Claude Code）的配置

原理

思源笔记软件可以在127.0.0.1:6806上访问到
SiYuan MCP Server - @porkll/siyuan-mcp 提供了相关mcp工具以及配置文件：

mcp.json:

{
  "mcpServers": {
    "siyuan-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@porkll/siyuan-mcp",
        "stdio",
        "--token",
        "你的API_TOKEN",
        "--baseUrl",
        "http://127.0.0.1:6806"
      ]
    }
  }
}

claude code:

1	claude mcp add --transport stdio porkll-siyuan-mcp npx -y @porkll/siyuan-mcp stdio --token YOUR_API_TOKEN_HERE --baseUrl http://127.0.0.1:6806

这里的API Token用于鉴权

本地 Cursor IDE 配置

配置过程

把配置信息粘贴到cursor的mcp.json就行，这种是全局方案，也可以在当前项目创建.cursor文件夹然后写到mcp.json也行

配置保存后，重新打开 Cursor。MCP 服务会在 Cursor 启动时自动加载。

远程 Linux 机器配置（Claude Code）

背景

远程 Linux 服务器上的 Claude Code 需要通过 MCP 协议访问本地 Windows 上运行的思源笔记。

远程 Linux 与本地通过 Tailscale 组网（固定 IP，不受网络切换影响）

1. 本地配置

记录 API Token（设置 → 关于 → API token）
确保 Tailscale 在思源启动前已连接，否则思源检测不到 Tailscale 网卡
重启思源后，检查 conf.json 中 localIPs 是否包含 Tailscale IP

2. 远程 Linux 代理绕过

如果远程 Linux 配置了 HTTP 代理，必须将 Tailscale IP 加入 no_proxy，否则请求会走代理导致 502。

编辑 ~/.zshrc（或 ~/.bashrc）：

1 2	export no_proxy=localhost,127.0.0.1,::1,100.66.247.77 export NO_PROXY=localhost,127.0.0.1,::1,100.66.247.77

3. 注册 MCP 服务器

使用 claude mcp add 命令注册（-s user 为全局级别）：

1	claude mcp add -s user --transport stdio siyuan-mcp -- npx -y @porkll/siyuan-mcp stdio --token <API_TOKEN> --baseUrl http://<TAILSCALE_IP>:6806

4. 验证连接

1
2
3

# 手动测试 API 是否可达
curl -s -H "Authorization: token <API_TOKEN>" http://<TAILSCALE_IP>:6806/api/system/version
# 预期返回: {"code":0,"msg":"","data":"3.1.30"}

确认通了后，重启 Claude Code 会话，MCP 工具即可使用。

踩坑记录

问题	原因	解决
MCP 连接失败 fetch failed	HTTP 代理拦截了 Tailscale IP 的请求	将 Tailscale IP 加入 `no_proxy`
curl 返回 502 Bad Gateway	同上，代理无法访问 Tailscale/内网地址	同上
ping 通但端口不通	思源未监听 Tailscale 网卡	确保 Tailscale 先于思源启动，或用 `--host=0.0.0.0` 启动思源
`localIPs` 无 Tailscale IP	思源启动时 Tailscale 未连接	先连 Tailscale 再启动思源
`~/.claude/mcp.json` 无效	Claude Code 通过 `claude mcp add` 管理 MCP 配置	使用命令注册而非手写 JSON

可用功能

配置成功后，可以通过自然语言使用以下工具：

类别	工具	功能
搜索	`unified_search`	按内容/文件名/标签组合搜索
查询	`get_document_content`	获取文档 Markdown 内容
查询	`get_document_tree`	获取文档树结构
查询	`get_recently_updated_documents`	获取最近更新文档
查询	`list_notebooks`	列出所有笔记本
写入	`create_document`	创建新文档
写入	`update_document`	覆盖更新文档
写入	`append_to_document`	追加内容到文档
写入	`append_to_daily_note`	追加到每日笔记
管理	`move_documents`	移动文档
标签	`list_all_tags` / `batch_replace_tag`	标签查询与批量替换
备份	`create_snapshot` / `rollback_to_snapshot`	快照与回滚