🧠 SiYuan MCP Server

简体中文 | English

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

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

当前版本：1.1.1

---

✨ 核心亮点

能力	说明
📚 笔记本与文档	创建、浏览、搜索、重命名、移动和删除
🧱 内容块	Markdown/DOM 插入、更新、移动、折叠、引用和批量操作
🔎 搜索	文档标题搜索、全文块搜索和 SQL 查询
🗃️ 原生数据库	创建 AV 数据库、字段、条目、单元格和批量更新
📎 文件与资源	Multipart 上传、工作空间文件读写和二进制 Base64 返回
🧩 模板与转换	Template、Sprig、Pandoc、Markdown 和资源导出
🛡️ 可选防护	删除类操作保护开关、路径白名单和响应上限
🤖 MCP 友好	structuredContent、isError、工具安全注解和纯净 stdio

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

🧭 工作原理

flowchart LR
    A["AI 客户端<br/>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。
2. 自动找到当前 MCP 客户端的配置文件，保留已有配置，加入名为 siyuan_note 的 MCP：
   command: npx
   args: ["-y", "siyuan-mcp@latest"]
   env: SIYUAN_HOST、SIYUAN_PORT、SIYUAN_TOKEN
3. 不要覆盖其他 MCP 配置，不要回显完整 Token，也不要把 Token 写入代码仓库。
4. 配置完成后重新加载 MCP；如果必须由我重启客户端，请明确提示。
5. 最后只调用 list_notebooks 测试连接，并告诉我当前已开启的笔记本名称。

除非 Node.js 不满足要求或必须重启客户端，否则不要中途询问，直接完成配置。

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 内容基本一致。

为兼容旧版配置，推荐继续使用 SIYUAN_HOST、SIYUAN_PORT 和 SIYUAN_TOKEN。连接远程实例、反向代理或带路径前缀的实例时，可以使用 SIYUAN_URL 覆盖 HOST/PORT：

{
  "env": {
    "SIYUAN_URL": "https://siyuan.example.com",
    "SIYUAN_TOKEN": "your-api-token-here"
  }
}

4. 验证连接

连接后可以让 AI 尝试：

检查思源连接状态，并列出当前打开的笔记本。

或者直接调用：

• check_siyuan_status
• list_notebooks
• get_version

---

🧰 功能地图

📚 笔记本

工具	用途
list_notebooks	列出所有笔记本及打开状态
create_notebook	创建笔记本
open_notebook / close_notebook	打开或关闭笔记本
rename_notebook	重命名笔记本
get_notebook_conf / set_notebook_conf	读取或保存配置
remove_notebook	删除笔记本，属于危险操作

📄 文档与文档树

工具	用途
create_doc	使用 Markdown 创建文档
search_docs	按标题搜索文档
list_docs	浏览指定路径下的文档
rename_doc / rename_doc_by_id	重命名文档
move_docs / move_docs_by_id	移动文档
get_hpath_by_id	获取人类可读路径
get_path_by_id	获取底层存储路径
remove_doc / remove_doc_by_id	删除文档

🧱 内容块

支持 Markdown 和思源 DOM 两种输入格式。

工具	用途
insert_block	在指定锚点插入块
append_block / prepend_block	在父块前后插入子块
update_block	更新块内容
move_block	调整块位置
batch_insert_blocks	批量插入
batch_update_blocks	批量更新
get_block_info	获取块元数据
get_block_kramdown	获取 Kramdown 源码
get_block_breadcrumb	获取块面包屑
fold_block / unfold_block	折叠或展开
transfer_block_ref	转移块引用
set_block_attrs / get_block_attrs	操作块属性

insert_block 需要至少提供一个位置参数：

• nextID
• previousID
• parentID

🔎 搜索与查询

全文搜索

search_blocks 使用思源原生全文搜索，支持：

• 普通关键词
• 查询语法
• 正则表达式
• 文档路径

... View full README on GitHub