思源笔记MCP服务器

思源MCP服务器

A. 模型上下文协议（MCP） 服务器用于 思源纸币，使AI助手（Claude、Cursor等）能够读取、写入和管理您的思源工作区，包括完整的CRUD 属性视图数据库 （思源的关系数据库系统，类似于Notion数据库）。

v2.1--针对LLM进行了优化

v2将刀具表面从70减小到 26个重点工具 （17核+9个数据库自动化），因为LLM使用更少、设计良好的工具表现更好。所有读取操作都合并到 siyuan_sql （利用思源的内置SQLite），而属性视图数据库保留了专用工具（它们使用JSON存储，而不是SQLite）。

v2.1 为添加自动视图选择 read_database （更喜欢未经过滤的“默认”视图）， viewId 用于可靠的跨设备同步。

刀具表面

核心工具

新的数据库自动化工具

支持的AV字段类型（创建/写入）： text, number, checkbox, select, mSelect, date, url, email, phone, mAsset, relation

支持的AV字段类型（创建/配置）： relation, rollup

只读/系统计算字段类型： created, updated, lineNumber, template

安装

先决条件

• 思源纸币 正在运行（本地或远程）
• Node.js 18+

获取您的API代币

思源： 设置>关于>API令牌 >复制。

选项1-npx（推荐）

添加到您的MCP客户端配置（Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["-y", "siyuan-query-mcp@latest"],
      "env": {
        "SIYUAN_API_TOKEN": "your-token-here"
      }
    }
  }
}

对于远程思源或非默认端口：

"env": {
  "SIYUAN_API_TOKEN": "your-token-here",
  "SIYUAN_API_URL": "http://192.168.1.100:6806"
}

选项2——来源

git clone https://github.com/MyrkoF/siyuan-mcp.git
cd siyuan-mcp/siyuan-mcp-server
npm install && npm run build

{
  "mcpServers": {
    "siyuan": {
      "command": "node",
      "args": ["/path/to/siyuan-mcp-server/dist/index.js"],
      "env": {
        "SIYUAN_API_TOKEN": "your-token-here"
      }
    }
  }
}

配置

旧别名： SIYUAN_TOKEN, SIYUAN_BASE_URL

工作区地图（推荐）

使用以下命令生成工作区地图 workspace_map 并将其粘贴到AI客户端的项目说明中。这为LLM预先提供了所有笔记本和数据库ID，跳过了发现调用。

Call workspace_map

返回笔记本树（2级）+所有数据库ID，格式为Markdown。

快速启动工作流

使用数据库创建文档

1. create_document(notebook: "id", path: "/My Page", title: "My Page")
   → returns document block ID

2. create_database(notebookId: "id", name: "My DB",
     parentDocId: "<doc ID from step 1>",
     fields: [{name: "Status", type: "select"}, {name: "Due", type: "date"}])
   → database appears embedded inside the document

读取和查询数据

# SQL for documents, blocks, tags, backlinks:
siyuan_sql(stmt: "SELECT * FROM blocks WHERE type='d' AND content LIKE '%project%'")

# AV databases (not in SQLite):
read_database(id: "avId")
read_database(id: "avId", filter: {field: "Status", value: "Active"})

移动文档

update_document(id: "docId", parentId: "targetParentDocId")
# Combine with rename:
update_document(id: "docId", title: "New Name", parentId: "targetId")

数据库视图和筛选

思源的 renderAttributeView API通过 视图 --每个视图都可以有自己的过滤器和排序。默认情况下，API使用GUI中最后一个活动的视图，这意味着过滤后的视图可以向MCP消费者隐藏条目。

约定：“默认”视图

创建一个名为的视图 Default （无过滤器）在您要以编程方式访问的每个数据库中。如果没有，MCP服务器将自动首选此视图 viewId 指定，确保无论GUI状态如何，您都能始终获得所有条目。

如果不存在“默认”视图，服务器将回退到当前活动视图（原始行为）。

你也可以通过 viewId 明确地 read_database 针对任何特定视图：

read_database(id: "avId", viewId: "specificViewId")

AV如何写入工作

思源对属性视图数据库使用双存储：

所有进入/现场操作均使用思源官方 /api/av/ 端点（内核原生）。仅 create_database 直接写入JSON文件（不存在用于创建DB的HTTP API）。一切都是纯HTTP的，不需要本地文件系统访问。

MCP资源

服务器将静态指南作为MCP资源公开：

• siyuan://static/guide --对象模型、ID查找、字段类型、什么不起作用
• siyuan://static/workflows --所有操作的分步CRUD工作流

在您的MCP客户端中阅读这些内容，以获取详细的使用指南。

消费者烟雾测试

构建后，您可以根据实时SiYuan实例验证完整的问题#1数据库自动化流程：

SIYUAN_API_TOKEN=your-token-here npm run smoke:siyuan

烟雾测试创建了一个临时笔记本，练习：

• 使用反向引用创建关系字段
• 汇总字段创建和回读
• 关系单元格写入
• 视图添加/更新
• 选择选项管理
• 分离式排→ 文件装订
• 文档支持的行创建
• 笔记本重命名

然后，它会删除临时笔记本。

对思源进行现场测试 3.6.4.

发展

npm install
npm run build
npx tsc --noEmit  # type-check only

归因

这个项目是 GALIAIS/思源mcp服务器.

原始项目为思源提供了基础的MCP服务器结构。这个叉子增加了：

• v2工具整合 --70个工具减少到26个重点工具，以提高LLM性能
• SQL首次读取 — siyuan_sql 替换15+个读取工具
• 完整属性视图数据库CRUD --创建、读取、写入、更新、删除数据库和条目
• 数据库嵌入 — create_database 随着 parentDocId 将数据库嵌入到页面中
• 文档移动 — update_document 随着 parentId 在父母之间移动文档
• 工作区地图 --项目说明的一个呼叫ID参考
• 普遍部署 --纯HTTP，没有 SIYUAN_WORKSPACE_PATH 需要

许可证

麻省理工学院——见 许可证