Siyuan Agent Mcp

npm version Node.js MCP License

面向 SiYuan 笔记 的高质量 MCP Server。它让 Claude Code、OpenCode、Cursor 等 MCP 客户端通过 SiYuan HTTP Kernel API 安全地读取、搜索、写入和整理你的本地笔记工作空间。

English documentation · Release notes · npm package

你可以用它做什么

5 分钟接入

1. 准备 SiYuan

先确认 SiYuan 正在运行，然后在 SiYuan 中复制 API token：

设置 -> 关于 -> API token

用 token 验证本机可以访问 Kernel API：

export SIYUAN_API_TOKEN="your-api-token-here"
curl -H "Authorization: Token $SIYUAN_API_TOKEN" http://127.0.0.1:6806/api/system/version

如果你只是第一次试用，建议先设置 SIYUAN_READ_ONLY=true，确认连接和搜索正常后再打开写权限。

2. 配置 MCP 客户端

多数用户不需要克隆本仓库，直接让客户端通过 npx 启动即可。

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["-y", "siyuan-agent-mcp"],
      "env": {
        "SIYUAN_API_URL": "http://127.0.0.1:6806",
        "SIYUAN_API_TOKEN": "your-api-token-here",
        "SIYUAN_READ_ONLY": "true"
      }
    }
  }
}

{
  "mcp": {
    "siyuan": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "siyuan-agent-mcp"],
      "environment": {
        "SIYUAN_API_URL": "http://127.0.0.1:6806",
        "SIYUAN_API_TOKEN": "your-api-token-here",
        "SIYUAN_READ_ONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["-y", "siyuan-agent-mcp"],
      "env": {
        "SIYUAN_API_URL": "http://127.0.0.1:6806",
        "SIYUAN_API_TOKEN": "your-api-token-here",
        "SIYUAN_READ_ONLY": "true"
      }
    }
  }
}

3. 第一次验证

重启或刷新 MCP 客户端后，按这个顺序调用工具：

验证读能力正常后，如果需要写入，把配置里的 SIYUAN_READ_ONLY 改为 false 并重启客户端。

常用任务速查

关键设计

环境变量

MCP 资源

Server 注册了以下 URI 模板，客户端可以直接获取上下文：

工具目录

日常使用时优先看上面的“常用任务速查”。下面是完整工具清单，便于做客户端能力审计或排查。

推荐工作流

定位笔记
  -> siyuan_list_notebooks / siyuan_list_docs / siyuan_search_notes

理解上下文
  -> siyuan_get_doc_outline / siyuan_get_backlinks / siyuan_get_block_breadcrumb

读取内容
  -> siyuan_read_doc / siyuan_get_block / siyuan_batch_get_blocks / MCP resources

编辑整理
  -> siyuan_append_block / siyuan_insert_block / siyuan_update_block / batch tools / move tools

富内容写入
  -> siyuan_upload_assets / siyuan_import_local_assets / siyuan_insert_asset_blocks / siyuan_insert_slash_block

分析和归档
  -> siyuan_query_blocks / siyuan_sql_query / daily-note tools

重要行为：

• siyuan_create_doc 在目标可读路径已存在时不会创建同名重复文档，而是返回已有文档 ID，并设置 existed=true、created=false。
• siyuan_create_doc 的 tags 可传逗号字符串、字符串数组或 #标签# 形式；若初始 Markdown 顶部误带 YAML front matter 或纯标签行，会抽取 tags 并从正文移除。
• siyuan_set_block_attrs 和 siyuan_batch_set_block_attrs 支持 tags 属性，并会把 #硬件# #上电测试# 规范化为思源需要的 硬件,上电测试。
• siyuan_insert_block 必须且只能提供一个锚点：previousID、nextID 或 parentID。
• siyuan_batch_insert_blocks 对同一个 parentID 的 parentID-only 批量插入会在发送给 SiYuan 前反向提交，从而让最终文档顺序与输入顺序一致。
• siyuan_upload_assets 会把文件流经 MCP 进程，默认单文件上限 512MB；大文件优先用 siyuan_import_local_assets 让 SiYuan Kernel 直接复制。
• siyuan_insert_slash_block 使用 SiYuan 可解析的 Markdown/HTML 片段插入富内容，避免调用方手写 <video>、<iframe> 或图表代码块模板。
• siyuan_remove_doc 和 siyuan_delete_block 必须提供与目标 ID 相同的 confirmId。
• siyuan_remove_notebook 默认隐藏；启用需要 SIYUAN_ENABLE_DANGEROUS_TOOLS=true，每次调用还必须提供 confirmId 和精确 confirmText。
• 只有已打开笔记本中的文档会被搜索索引覆盖。

手工端到端检查

在 SiYuan 正在运行时执行：

npx @modelcontextprotocol/inspector node dist/index.js

建议按以下链路验证：

siyuan_health
  -> siyuan_list_notebooks
  -> siyuan_list_docs
  -> siyuan_search_notes
  -> siyuan_read_doc
  -> siyuan_get_doc_outline / siyuan_get_backlinks
  -> siyuan_create_doc
  -> siyuan_append_block
  -> siyuan_insert_slash_block kind=mermaid
  -> siyuan_upload_assets insertAfterUpload=true
  -> siyuan_batch_update_blocks
  -> siyuan_search_notes 确认已索引
  -> siyuan_delete_block with confirmId
  -> siyuan_remove_doc with confirmId
  -> siyuan_create_daily_note
  -> siyuan_append_daily_note_block
  -> siyuan_sql_query 拒绝 DELETE FROM blocks

常见问题

siyuan_health 连接失败

先确认 SiYuan 正在运行，SIYUAN_API_URL 指向 Kernel API 地址，而不是普通网页地址。默认本机地址通常是 http://127.0.0.1:6806。

客户端看不到写入工具

检查 SIYUAN_READ_ONLY 是否为 true。只读模式会直接移除所有写入和状态变更工具。

搜索不到刚写入的内容

写入工具会刷新 transaction，但 SiYuan 索引仍可能短暂延迟。服务端默认会在索引中状态下等待 SIYUAN_RETRY_INDEXING_MS 后自动重试一次。

SQL 被拒绝

siyuan_sql_query 只允许只读 SELECT，必须带数字 LIMIT <= 1000。写入、DDL、多语句或超大查询都会被拒绝。

删除工具调用失败

删除文档和块时，confirmId 必须和目标 ID 完全一致。删除笔记本还需要开启 SIYUAN_ENABLE_DANGEROUS_TOOLS=true，并提供精确的 confirmText。

本地开发

克隆仓库后执行：

npm install
npm run build
npm test

项目结构：

src/
  index.ts            # 组装 server，注册工具，连接 stdio
  config.ts           # 环境变量解析与校验
  client.ts           # SiYuanClient：认证、错误处理、flushTransaction
  types.ts            # SiYuan 数据结构
  schemas.ts          # 共享 Zod schema
  format.ts           # ID 校验、响应格式化、转义、截断
  tooling.ts          # 工具注册辅助和 annotations
  resources.ts        # MCP resource templates
  tools/              # 按工具分组拆分模块
test/                 # node --test 单元测试和工具契约测试，针对 dist/ 运行
evaluation/           # mcp-builder 评估套件

License

MIT