简体中文 |英语

让 Claude、Cursor、Codex 等 AI 客户端安全地读取和操作思源笔记。

siyuan-mcp 是一个基于 Model Context Protocol 的思源笔记 MCP 服务器。它通过思源 Kernel API 提供笔记本、文档、内容块、全文搜索、原生数据库、资源文件和导出等能力，并针对 AI 自动化场景增加了结构化返回、安全注解与默认防护。

当前版本：1.1.1

---

✨ 核心亮点

项目目前提供约 69 个面向 AI 使用场景设计的工具。它选择性封装稳定且实用的思源接口，不追求暴露全部内核私有 API。

🧭 工作原理

所有调试信息只写入 stderr，stdout 始终保留给 MCP JSON-RPC，避免客户端因混入普通日志而断开连接。

---

🚀 快速开始

🤖 让智能体自动配置

只需复制下面的提示词，并填写 MCP 客户端和思源 Token。默认连接本机 127.0.0.1:6806;使用其他地址时再修改 HOST 和 PORT。

1.准备环境

• Node.js >= 18
• 已启动的思源笔记
• 思源 API 令牌

API 令牌获取位置：

思源笔记 → 设置 → 关于 → API Token

2.使用 npx 启动

MCP 服务器通常由 AI 客户端自动启动，不需要单独打开终端常驻运行。

3.配置 MCP 客户端

该配置形式可用于 Cursor、Claude Desktop 以及其他支持 stdio MCP 的客户端。不同客户端的配置文件位置可能不同，但 command、args 和 env 内容基本一致。

🧠 SiYuan MCP Server

简体中文 | English

让 Claude、Cursor、Codex 等 AI 客户端安全地读取和操作思源笔记。

siyuan-mcp 是一个基于 Model Context Protocol 的思源笔记 MCP 服务器。它通过思源 Kernel API 提供笔记本、文档、内容块、全文搜索、原生数据库、资源文件和导出等能力，并针对 AI 自动化场景增加了结构化返回、安全注解与默认防护。

当前版本：1.1.1

---

✨ 核心亮点

项目目前提供约 69 个面向 AI 使用场景设计的工具。它选择性封装稳定且实用的思源接口，不追求暴露全部内核私有 API。

🧭 工作原理

flowchart LR
    A["AI 客户端Claude / Cursor / Codex"] -->|MCP stdio| B["SiYuan MCP Server"]
    B -->|HTTP + Token| C["SiYuan Kernel API"]
    C --> D["笔记本 / 文档 / 内容块"]
    C --> E["数据库 AV"]
    C --> F["资源 / 模板 / 导出"]

所有调试信息只写入 stderr，stdout 始终保留给 MCP JSON-RPC，避免客户端因混入普通日志而断开连接。

---

🚀 快速开始

🤖 让智能体自动配置

只需复制下面的提示词，并填写 MCP 客户端和思源 Token。默认连接本机 127.0.0.1:6806；使用其他地址时再修改 HOST 和 PORT。

请帮我配置最新版 siyuan-mcp。

用户配置：
- MCP 客户端：{{填写 Codex、Claude Desktop、Cursor 等}}
- 思源 API Token：{{填写 Token}}
- SIYUAN_HOST：127.0.0.1
- SIYUAN_PORT：6806

请直接执行：

1. 检查 Node.js 是否已安装且版本不低于 18。
   - 如果 Node.js 未安装或版本低于 18，只告诉我需要安装或升级 Node.js，然后停止。
   - 不要尝试用其他方式绕过 Node.js 要求。

2. 自动找到当前 MCP 客户端的配置文件，保留已有配置，只新增或更新名为 `siyuan_note` 的 MCP 配置：
   - command: `npx`
   - args: `["-y", "siyuan-mcp@latest"]`
   - env:
     - `SIYUAN_HOST`
     - `SIYUAN_PORT`
     - `SIYUAN_TOKEN`

3. 安全要求：
   - 不要覆盖、删除或重排其他 MCP 配置。
   - 不要在回复中回显完整 Token。
   - 不要把 Token 写入项目代码、仓库文件、临时脚本或日志。
   - Token 只能写入 MCP 客户端的用户级配置文件。

4. 配置完成后，尝试让当前 MCP 客户端重新加载 MCP 配置。
   - 如果当前客户端支持在设置里重启/刷新 MCP 配置，请提示我去设置里执行该操作，然后停止，等我完成后再继续测试。
   - 如果当前客户端必须完整重启才能加载新的 MCP，请明确告诉我“需要重启客户端”，然后停止。
   - 不要为了测试连接而手写 MCP JSON-RPC 脚本、临时 Node 脚本或自定义客户端。

5. MCP 重新加载成功后，只使用当前 MCP 客户端已经加载的 `siyuan_note` MCP 能力测试连接：
   - 优先直接调用 `list_notebooks` 工具。
   - 如果客户端只暴露了等价的 notebooks 资源而没有暴露工具函数，可以读取该 notebooks 资源。
   - 不要调用其他工具或读取其他内容。

6. 最后只告诉我：
   - 配置是否成功；
   - 是否需要在设置里重启/刷新 MCP，或是否需要完整重启客户端；
   - 当前已开启的笔记本名称。

除非 Node.js 不满足要求、找不到配置文件、需要你去设置里重启/刷新 MCP、或必须完整重启客户端，否则不要中途询问，直接完成配置。

1. 准备环境

• Node.js >= 18
• 已启动的思源笔记
• 思源 API Token

API Token 获取位置：

思源笔记 → 设置 → 关于 → API Token

2. 使用 npx 启动

npx -y siyuan-mcp@latest

MCP 服务器通常由 AI 客户端自动启动，不需要单独打开终端常驻运行。

3. 配置 MCP 客户端

{
  "mcpServers": {
    "siyuan_note": {
      "command": "npx",
      "args": ["-y", "siyuan-mcp@latest"],
      "env": {
        "SIYUAN_HOST": "127.0.0.1",
        "SIYUAN_PORT": "6806",
        "SIYUAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

该配置形式可用于 Cursor、Claude Desktop 以及其他支持 stdio MCP 的客户端。不同客户端的配置文件位置可能不同，但 command、args 和 env 内容基本一致。