Skip to main content
Glama
SiYuan MCP Server

SiYuan MCP Server

by xgq18237

🧠 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。

Related MCP server: SiYuan Note MCP Server

🧭 工作原理

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 未安装或版本低于 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 内容基本一致。

为兼容旧版配置,推荐继续使用 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 使用思源原生全文搜索,支持:

  • 普通关键词

  • 查询语法

  • 正则表达式

  • 文档路径过滤

  • 块类型过滤

  • 分页、排序和按文档分组

SQL 查询

sql_query 会将 SQL 原样交给思源 Kernel API,不限制语句类型,也不会自动补充 LIMIT。调用写入、删除或结构变更语句前,请自行确认影响;查询大量数据时应主动添加 LIMIT。

示例:

SELECT id, content, hpath, updated
FROM blocks
WHERE type = 'd'
ORDER BY updated DESC
LIMIT 20

优先使用 search_docs 和 search_blocks。只有在需要精确字段、聚合或复杂过滤时才建议使用 SQL。


🗃️ 原生数据库支持

数据库工具直接操作思源 Attribute View(AV),不是 Markdown 表格。

工具

用途

create_database

插入 AV 块并初始化数据库存储

get_database

分页渲染数据库

get_database_keys

获取字段定义

rename_database

重命名数据库

add_database_column

添加字段

remove_database_column

删除字段

append_database_rows

添加非绑定条目

set_database_cell

设置单元格

batch_set_database_cells

批量设置单元格

remove_database_rows

删除条目

创建数据库

{
  "parentID": "20260628160104-6d71dw0",
  "name": "项目清单",
  "columns": [
    {
      "name": "状态",
      "type": "select"
    },
    {
      "name": "完成",
      "type": "checkbox"
    },
    {
      "name": "备注",
      "type": "text"
    }
  ]
}

创建过程会自动完成:

  1. 生成合法 AV ID。

  2. 插入 NodeAttributeView 块。

  3. 调用 renderAttributeView 创建数据库存储。

  4. 设置数据库名称。

  5. 创建附加字段。

如果初始化失败,服务器会尝试回滚已插入的数据库块。

添加条目

{
  "avID": "20260628163701-rc230o0",
  "blockID": "20260628163701-7rmjwsl",
  "titles": [
    "整理需求",
    "实现功能",
    "发布版本"
  ]
}

更新单元格

set_database_cell 的 value 使用思源 AV Value 结构。

文本字段示例:

{
  "avID": "数据库 ID",
  "keyID": "字段 ID",
  "itemID": "条目 ID",
  "value": {
    "text": {
      "content": "已经完成"
    }
  }
}

复选框字段示例:

{
  "value": {
    "checkbox": {
      "checked": true
    }
  }
}

常用字段类型包括:

text、number、date、select、mSelect、url、email、phone、mAsset、checkbox、created 和 updated。


📎 文件与资源

资源上传

upload_asset 使用真正的 HTTP Multipart 表单,不会把文件路径误当作 JSON 发送。

{
  "assetsDirPath": "/assets/",
  "files": [
    "C:\\Users\\me\\Pictures\\diagram.png"
  ]
}

本地文件必须位于 SIYUAN_MCP_UPLOAD_ROOTS 允许的目录中。

工作空间文件

工具

用途

get_file

获取文本、JSON 或二进制文件

put_file

Multipart 写入文件或创建目录

read_dir

浏览目录

rename_file

重命名文件

remove_file

删除文件

返回策略:

  • JSON:直接返回结构化对象

  • 文本:返回 UTF-8 字符串

  • 二进制:返回 Base64、MIME 类型和字节数

put_file 支持三种输入方式:

  • filePath:本地文件路径

  • file:UTF-8 文本

  • contentBase64:Base64 数据


🛡️ 安全设计

可选的危险操作保护

删除类操作默认可用。若希望 MCP 只允许创建、读取和普通更新,可显式开启保护:

SIYUAN_MCP_PROTECT_DESTRUCTIVE=true

只有该参数显式为 true 或 1 时,以下操作才会被拒绝:

  • 删除笔记本、文档和内容块

  • 删除数据库字段或条目

  • 覆盖、移动或删除工作空间文件

未配置、设为 false 或设为 0 时,删除类操作正常可用。

升级提醒:旧变量 SIYUAN_MCP_ALLOW_DESTRUCTIVE 已不再参与判断。若希望继续保持“拒绝删除”的行为,请改为 SIYUAN_MCP_PROTECT_DESTRUCTIVE=true。

SQL 直接执行

sql_query 默认允许思源 Kernel API 支持的 SQL,不再区分“安全 SQL”和“危险 SQL”,也不自动添加行数限制。建议在查询语句中自行添加 LIMIT,并谨慎执行写入或结构变更语句。

旧变量 SIYUAN_MCP_ALLOW_UNSAFE_SQL 和 SIYUAN_MCP_SQL_MAX_ROWS 已不再使用。

工作空间写入白名单

默认允许:

/data/assets,/temp

自定义:

SIYUAN_MCP_WRITE_PATH_PREFIXES=/data/assets,/data/templates,/temp

本地上传目录白名单

默认只允许 MCP 进程当前目录。

Windows:

SIYUAN_MCP_UPLOAD_ROOTS=C:\Users\me\Pictures;C:\Users\me\Documents

Linux/macOS:

SIYUAN_MCP_UPLOAD_ROOTS=/home/me/Pictures:/home/me/Documents

连接地址

SIYUAN_HOST 和 SIYUAN_URL 均可指向本机或远程实例,HTTP 与 HTTPS 都可以使用,MCP 不额外限制协议。通过公网或不可信网络连接时,仍建议由部署者使用 HTTPS 保护 API Token 和传输内容。


⚙️ 环境变量

变量

默认值

说明

SIYUAN_URL

—

完整思源 URL,优先于 HOST/PORT

SIYUAN_HOST

127.0.0.1

思源主机

SIYUAN_PORT

6806

思源端口

SIYUAN_TOKEN

空

思源 API Token

SIYUAN_MCP_PROTECT_DESTRUCTIVE

false

显式设为 true 或 1 时拒绝删除类操作

SIYUAN_MCP_WRITE_PATH_PREFIXES

/data/assets,/temp

工作空间写入白名单

SIYUAN_MCP_UPLOAD_ROOTS

当前目录

本地上传目录白名单

SIYUAN_MCP_TIMEOUT_MS

120000

单次 API 请求超时(2 分钟)

SIYUAN_MCP_MAX_RESPONSE_BYTES

10485760

最大响应字节数

SIYUAN_MCP_MAX_TEXT_CHARS

30000

MCP 文本预览长度

SIYUAN_MCP_DEBUG

0

向 stderr 输出端点、状态和耗时

调试模式不会输出请求 Token 或笔记正文。


🐳 Docker

本项目采用 MCP stdio 传输。容器必须由 MCP 客户端以前台交互模式启动,因此需要 -i。

使用已发布镜像

Docker Hub 镜像为 zhizhiqq/siyuan-mcp。使用 latest 可获得最新版,也可以固定版本标签以确保环境可复现:

docker pull zhizhiqq/siyuan-mcp:latest
# 当前版本:
docker pull zhizhiqq/siyuan-mcp:v1.1.1

MCP 客户端配置

下面的配置用于连接运行在宿主机上的思源:

{
  "mcpServers": {
    "siyuan_note": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host",
        "host.docker.internal:host-gateway",
        "-e",
        "SIYUAN_HOST=host.docker.internal",
        "-e",
        "SIYUAN_PORT=6806",
        "-e",
        "SIYUAN_TOKEN",
        "zhizhiqq/siyuan-mcp:latest"
      ],
      "env": {
        "SIYUAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

注意:

  • 容器内的 127.0.0.1 指向容器自身。

  • 访问宿主机思源应使用 host.docker.internal。

  • --add-host=host.docker.internal:host-gateway 让 Linux 也能使用相同的宿主机地址;Docker Desktop 已原生支持该地址。

  • 必须保留 -i,MCP 通过容器的 stdin/stdout 通信。

  • --rm 会在进程停止后自动删除容器。

  • stdio MCP 不应使用普通后台 Compose 服务代替客户端进程。

  • docker compose run --rm siyuan-mcp-server 可用于手工连通性检查。

在 Docker 中上传本地文件

容器不能直接读取任意宿主机文件。需要将允许上传的宿主机目录以只读方式挂载到 /uploads,并设置 SIYUAN_MCP_UPLOAD_ROOTS=/uploads。在上方配置的镜像名称之前加入:

[
  "--mount",
  "type=bind,src=/宿主机/文件绝对路径,dst=/uploads,readonly",
  "-e",
  "SIYUAN_MCP_UPLOAD_ROOTS=/uploads"
]

请将 /宿主机/文件绝对路径 替换为实际绝对路径。只有该挂载目录内的文件能够上传。

本地构建镜像

如需从当前仓库自行构建,而不是使用 Docker Hub 镜像:

docker build -t siyuan-mcp-server .

然后将 MCP 配置中的 zhizhiqq/siyuan-mcp:latest 替换为 siyuan-mcp-server。


📦 本地安装

git clone https://github.com/xgq18237/siyuan_mcp_server.git
cd siyuan_mcp_server
npm ci
npm run build
node dist/index.js

本地源码配置示例:

{
  "mcpServers": {
    "siyuan_note": {
      "command": "node",
      "args": [
        "C:\\path\\to\\siyuan_mcp_server\\dist\\index.js"
      ],
      "env": {
        "SIYUAN_HOST": "127.0.0.1",
        "SIYUAN_PORT": "6806",
        "SIYUAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

🧪 开发与检查

npm ci
npm run check
npm test

命令

说明

npm run dev

使用 tsx 运行源码

npm run check

TypeScript 严格类型检查

npm run build

构建到 dist/

npm test

执行类型检查并重新构建

npm run rebuild

清理后重新构建

npm run test:docker

构建测试 Docker 镜像

涉及真实思源数据的集成验证应在隔离笔记本中进行,并在完成后清理临时文档、数据库、资源与导出文件。

项目结构

siyuan_mcp_server/
├─ src/
│  ├─ index.ts           # MCP 服务与资源
│  ├─ siyuan-client.ts   # JSON / Multipart / 二进制传输层
│  └─ tools.ts           # 工具定义、安全策略与调用实现
├─ dist/                 # 编译后的发布文件
├─ Dockerfile
├─ docker-compose.yml
├─ env.example
└─ package.json

🔧 常见问题

MCP 客户端无法连接

依次确认:

  1. 思源是否正在运行。

  2. SIYUAN_HOST、SIYUAN_PORT 是否正确;使用远程反向代理时再检查 SIYUAN_URL。

  3. API Token 是否有效。

  4. Node.js 是否满足版本要求。

  5. 是否有普通日志写入 stdout。

可以先在浏览器打开:

http://127.0.0.1:6806

返回 401、403 或鉴权失败

重新复制思源“设置 → 关于”中的 API Token,并重启 MCP 进程。不要在 Token 前后加入引号以外的空格。

删除工具提示危险操作保护已开启

当前 MCP 进程显式开启了保护。需要恢复删除能力时,移除该变量或设置:

SIYUAN_MCP_PROTECT_DESTRUCTIVE=false

上传文件提示不在允许目录

将文件移动到允许目录,或配置:

SIYUAN_MCP_UPLOAD_ROOTS=允许的本地目录

Docker 中无法访问思源

不要使用 127.0.0.1 访问宿主机,改用:

SIYUAN_HOST=host.docker.internal

数据库块存在但无法正常显示

数据库不仅需要 AV 块,还需要对应的 AV 存储。请使用 create_database,它会自动调用 renderAttributeView 完成初始化。

输出过大被截断

优先使用分页、搜索条件或 SQL LIMIT。必要时调整:

SIYUAN_MCP_MAX_RESPONSE_BYTES
SIYUAN_MCP_MAX_TEXT_CHARS

🤝 贡献

欢迎提交 Issue 和 Pull Request。新增工具时建议同时考虑:

  • 是否适合 AI 自动调用

  • 是否属于危险或破坏性操作

  • 是否需要分页和输出上限

  • 是否应返回结构化数据

  • 是否涉及 Multipart 或二进制响应

  • 是否会把敏感内容写入日志

📄 License

MIT

Available Tools

69 tools
add_database_columnC

添加数据库字段

Inputs: avID (required), name (required), type (required), icon, +1 more.

append_blockA

在父块末尾插入子块

Inputs: data (required), parentID (required), dataType.

append_database_rowsC

以标题批量添加非绑定数据库条目

Inputs: avID (required), titles (required), viewID, blockID.

batch_insert_blocksC

批量插入块

Inputs: blocks (required).

batch_set_database_cellsB

批量设置数据库单元格;values 使用思源批量 AV Value 结构

Inputs: avID (required), values (required).

batch_update_blocksC

批量更新块

Inputs: blocks (required).

check_siyuan_statusA
Read-onlyIdempotent

检查连接、鉴权、笔记本和 SQL 可用性

Inputs: no named parameters.

close_notebookB

关闭指定笔记本

Inputs: notebook (required).

create_databaseB

创建并初始化原生思源数据库,可同时创建字段

Inputs: parentID (required), name, columns.

create_docB

在指定笔记本中新建 Markdown 文档

Inputs: path (required), markdown (required), notebook (required).

create_notebookB

创建新笔记本

Inputs: name (required).

delete_blockC
Destructive

删除块

Inputs: id (required).

export_md_contentC
Read-onlyIdempotent

导出文档 Markdown

Inputs: id (required).

export_resourcesB
Read-onlyIdempotent

导出文件与目录

Inputs: paths (required), name.

flush_transactionB

等待思源事务队列落盘

Inputs: no named parameters.

fold_blockD

折叠块

Inputs: id (required).

get_block_attrsC
Read-onlyIdempotent

获取块属性

Inputs: id (required).

get_block_breadcrumbA
Read-onlyIdempotent

获取块的面包屑路径

Inputs: id (required), excludeTypes.

get_block_infoB
Read-onlyIdempotent

获取块的元数据

Inputs: id (required).

get_block_kramdownB
Read-onlyIdempotent

获取块 Kramdown 源码

Inputs: id (required).

get_boot_progressA
Read-onlyIdempotent

获取思源启动进度

Inputs: no named parameters.

get_child_blocksB
Read-onlyIdempotent

获取直接子块

Inputs: id (required).

get_current_timeA
Read-onlyIdempotent

获取思源内核当前时间

Inputs: no named parameters.

get_databaseC
Read-onlyIdempotent

分页渲染数据库

Inputs: avID (required), page, query, viewID, +3 more.

get_database_keysB
Read-onlyIdempotent

获取数据库字段定义

Inputs: avID (required).

get_fileA
Read-onlyIdempotent

读取工作空间文件;文本/JSON直接返回,二进制以 Base64 返回

Inputs: path (required).

get_hpath_by_idA
Read-onlyIdempotent

根据 ID 获取人类可读路径

Inputs: id (required).

get_hpath_by_pathA
Read-onlyIdempotent

根据存储路径获取人类可读路径

Inputs: path (required), notebook (required).

get_ids_by_hpathC
Read-onlyIdempotent

根据人类可读路径获取 ID

Inputs: path (required), notebook (required).

get_notebook_confB
Read-onlyIdempotent

获取笔记本配置

Inputs: notebook (required).

get_path_by_idB
Read-onlyIdempotent

根据 ID 获取存储路径

Inputs: id (required).

get_versionA
Read-onlyIdempotent

获取思源版本

Inputs: no named parameters.

get_workspace_infoA
Read-onlyIdempotent

获取脱敏后的 MCP 连接与安全配置

Inputs: no named parameters.

insert_blockB

在指定锚点插入块;nextID、previousID、parentID 至少提供一个

Inputs: data (required), nextID, dataType, parentID, +1 more.

list_docsB
Read-onlyIdempotent

列出指定笔记本路径下的文档

Inputs: path (required), notebook (required), sort, flashcard, +2 more.

list_notebooksA
Read-onlyIdempotent

列出所有思源笔记本及其打开状态

Inputs: no named parameters.

move_blockC

移动块;previousID 或 parentID 至少提供一个

Inputs: id (required), parentID, previousID.

move_docsC

移动一组文档

Inputs: toPath (required), fromPaths (required), toNotebook (required).

move_docs_by_idC

按 ID 移动一组文档

Inputs: toID (required), fromIDs (required).

open_notebookB

打开指定笔记本

Inputs: notebook (required).

pandoc_convertC

执行思源 Pandoc 转换

Inputs: dir (required), args (required).

prepend_blockB

在父块开头插入子块

Inputs: data (required), parentID (required), dataType.

push_err_msgB

向思源界面推送错误消息

Inputs: msg (required), timeout.

push_msgB

向思源界面推送普通消息

Inputs: msg (required), timeout.

put_fileC
Destructive

通过 Multipart 写入工作空间文件

Inputs: path (required), file, isDir, modTime, +4 more.

read_dirC
Read-onlyIdempotent

列出工作空间目录

Inputs: path (required).

remove_database_columnB
Destructive

删除数据库字段

Inputs: avID (required), keyID (required), removeRelationDest.

remove_database_rowsC
Destructive

删除数据库条目

Inputs: avID (required), itemIDs (required).

remove_docA
Destructive

按路径删除文档

Inputs: path (required), notebook (required).

remove_doc_by_idB
Destructive

按 ID 删除文档

Inputs: id (required).

remove_fileC
Destructive

删除工作空间文件

Inputs: path (required).

remove_notebookA
Destructive

删除笔记本及其内容;可通过保护开关禁用

Inputs: notebook (required).

rename_databaseD

重命名数据库

Inputs: avID (required), name (required).

rename_docA

按存储路径重命名文档

Inputs: path (required), title (required), notebook (required).

rename_doc_by_idC

按 ID 重命名文档

Inputs: id (required), title (required).

rename_fileC
Destructive

重命名工作空间文件

Inputs: path (required), newPath (required).

rename_notebookC

重命名笔记本

Inputs: name (required), notebook (required).

render_sprigC

渲染 Sprig 模板

Inputs: template (required).

render_templateC

渲染模板文件

Inputs: id (required), path (required).

search_blocksB
Read-onlyIdempotent

使用思源全文搜索查找内容块

Inputs: query (required), page, paths, types, +4 more.

search_docsB
Read-onlyIdempotent

按标题搜索文档

Inputs: query (required), flashcard, excludeIDs.

set_block_attrsC

设置块属性

Inputs: id (required), attrs (required).

set_database_cellB

设置单个数据库单元格;value 使用思源 AV Value JSON 结构

Inputs: avID (required), keyID (required), value (required), itemID (required).

set_notebook_confC

保存笔记本配置

Inputs: conf (required), notebook (required).

sql_queryB
Destructive

执行 SQL 语句;调用方应自行确认写入类语句的影响

Inputs: sql (required).

transfer_block_refC

转移块引用

Inputs: toID (required), fromID (required), refIDs.

unfold_blockD

展开块

Inputs: id (required).

update_blockC

更新块内容

Inputs: id (required), data (required), dataType.

upload_assetB

上传一个或多个本地资源文件

Inputs: files (required), assetsDirPath (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 69 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. Even where similar operations exist (e.g., rename by path vs ID), the descriptions clearly differentiate the parameter style. The set is well-organized by category (notebooks, docs, blocks, databases, files), minimizing confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case. Variations like 'rename_doc_by_id' or 'get_hpath_by_path' follow a predictable extension scheme. No mixing of styles or ambiguous verbs.

    Tool Count4/5

    69 tools is large but appropriate for the comprehensive SiYuan note-taking domain, covering notebooks, documents, blocks, databases, files, and utilities. While slightly overwhelming, each tool serves a specific purpose and the scope justifies the count.

    Completeness5/5

    The tool surface covers all major CRUD operations for notebooks, documents, blocks, and databases, plus file management, export, templating, and system utilities. There are no obvious dead ends or missing essential operations for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables interaction with SiYuan Note through its API for comprehensive note management. Supports searching, creating, editing documents, managing notebooks, and daily notes operations through natural language commands.
      15
      Apache 2.0
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI assistants to interact with SiYuan Note for comprehensive notebook management, document editing, and block-level content operations. It supports advanced features like full-text search and SQL queries via secure API integration.
      3
      34 npm
      40
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to create, read, update, and manage SiYuan notes, supporting notebook management, document operations, block editing, database attribute views, search, file operations, and export.
      11
      1
      MIT