🧠 思源笔记 MCP 服务器

让 AI 助手直接操作思源笔记的 Model Context Protocol 服务器

适配版本

| 项目 | 版本 | |---|---| | 思源笔记 | >= 3.0.0（已验证 3.7.1） | | SiYuan API | docs/API.md（50 个非 Database 端点） | | Node.js | >= 18.0.0 | | MCP SDK | @modelcontextprotocol/sdk ^1.8.0 |

快速开始

# 直接运行
SIYUAN_TOKEN=your-api-token npx @fromsko/siyuan-mcp-server

# 全局安装
npm install -g @fromsko/siyuan-mcp-server
SIYUAN_TOKEN=your-api-token siyuan-mcp-server

| 环境变量 | 必需 | 说明 | 默认值 | |---|---|---|---| | SIYUAN_TOKEN | ✅ | 思源笔记 API Token（设置 → 关于） | — | | SIYUAN_API_URL | ❌ | 思源 API 地址 | http://localhost:6806 |

给 LLM 的配置说明

如果你是 AI 助手，请将以下配置添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["-y", "@fromsko/siyuan-mcp-server"],
      "env": {
        "SIYUAN_TOKEN": "<用户提供的 API Token>",
        "SIYUAN_API_URL": "http://localhost:6806"
      }
    }
  }
}

配置文件位置：

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Cursor: .cursor/mcp.json

配置完成后重启客户端，即可使用 50 个思源笔记操作工具（笔记本管理、文档操作、块级编辑、全文搜索、SQL 查询等）。

功能概览

| 类别 | 命令空间 | 端点数 | 能力 | |---|---|---|---| | 📓 笔记本 | notebook.* | 8 | 创建/删除/重命名/配置 | | 📄 文档 | filetree.* | 11 | 创建/删除/移动/重命名（支持 hpath 自动解析） | | 🧱 块操作 | block.* | 11 | 插入/更新/删除/移动/折叠/展开 | | 🔍 搜索 | search.* / sql.* | 3 | 全文搜索/SQL 查询/事务刷新 | | 📎 属性 | attr.* | 2 | 设置/获取块属性 | | 📁 文件 | file.* | 5 | 读写/删除/重命名/列目录 | | 📋 模板 | template.* | 2 | 渲染模板/Sprig | | 📤 导出 | export.* | 2 | 导出 Markdown/导出资源包 | | 🔄 转换 | convert.* | 1 | Pandoc 格式转换 | | 🔔 通知 | notification.* | 2 | 推送消息 | | 🌐 网络 | network.* | 1 | 正向代理 | | ⚙️ 系统 | system.* | 3 | 版本/启动进度/当前时间 |

开发

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

详细开发文档：

| 文档 | 说明 | |---|---| | docs/development.md | 开发指南、项目结构、添加端点流程 | | docs/mcp-usage.md | MCP 使用指南 | | docs/ref/siyuan-api.md | 官方 SiYuan API 文档 | | llms.txt | LLM 导向的项目简介 | | AGENTS.md | 提交规范和开发约束 |

问题排查

无法连接思源笔记 → 检查：思源是否运行、Token 是否正确、端口是否正确（默认 6806）

命令执行失败 → 确认笔记本/文档存在、Token 权限足够

连接远程思源 → 设置 SIYUAN_API_URL=http://your-server:6806

开源协议

ISC — 详见 LICENSE

致谢

• 🌟 onigeya — 原始项目
• 🙏 思源笔记 团队
• 🤖 Anthropic — MCP 协议