思源MCP服务器
中文文档 |英语
SiYuan Note的模型上下文协议（MCP）服务器，使Claude、Cursor和其他MCP兼容工具等AI助手能够与您的SiYuan笔记无缝交互。
⚠️ Important Notice | 重要声明
英语：
这个项目中的代码主要是在人工智能的帮助下开发的。虽然已经进行了功能测试，但全面的代码审查尚未完成。在使用本项目之前，请注意并接受以下内容：
- 代码可能包含未发现的问题或潜在风险
- 使用前进行必要的代码审查和测试
- 用户承担因使用本项目而产生的所有风险和责任
- 建议在生产使用前进行彻底验证
请谨慎使用，并自行承担风险。
______________________________________________________________________
中文：
本项目代码主要由 AI 辅助开发，仅进行了功能性测试，未对所有代码进行完整审查。使用本项目前，请充分了解并接受以下内容：
- 代码可能存在未发现的问题或潜在风险
- 请在使用前进行必要的代码审查和测试
- 使用者需自行承担使用本项目所产生的风险和责任
- 建议在生产环境使用前进行充分的验证
请谨慎使用，并对自己的选择负责。
✨ 特性
- 🚀 完整的MCP（模型上下文协议）实现
- 📝 全面操作思源纸币的15个基本工具
- 🔍 统一搜索（内容、文件名、标签和组合）
- 📁 文档管理（创建、读取、更新、移动、树）
- 📅 每日笔记支持自动创建
- 📚 笔记本操作
- 📸 快照管理（备份和恢复）
- 🏷️ 标签管理（列表、替换）
- 💻 用TypeScript编写，具有完整的类型定义
- 🌐 适用于Claude Desktop、Cursor和任何兼容MCP的客户端
📦 安装
选项1：从源代码安装（推荐）
# Clone the repository
git clone https://github.com/porkll/siyuan-mcp.git
cd siyuan-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Install globally
npm install -g .选项2：从npm安装
# Install globally
npm install -g @porkll/siyuan-mcp
# Or use npx (no installation needed)
npx @porkll/siyuan-mcp全局安装后 siyuan-mcp 命令将在全球范围内可用。
🔧 配置
先决条件
- 获取您的思源API代币：
- 打开思源纸币 - 转到“设置”→ 关于→ API代币 - 复制令牌
- 确保思源正在运行：
- 默认URL: http://127.0.0.1:6806 - 如果使用其他端口，请调整 baseUrl 相应地
配置光标
在以下位置编辑MCP配置文件 ~/.cursor/mcp.json:
{
"mcpServers": {
"siyuan-mcp": {
"command": "npx",
"args": [
"-y",
"@porkll/siyuan-mcp",
"stdio",
"--token",
"YOUR_API_TOKEN_HERE",
"--baseUrl",
"http://127.0.0.1:6806"
]
}
}
}备注：如果全局安装，则可以使用 "command": "siyuan-mcp" 而不是 "command": "npx".
为Claude桌面配置
在以下位置编辑配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"siyuan-mcp": {
"command": "npx",
"args": [
"-y",
"@porkll/siyuan-mcp",
"stdio",
"--token",
"YOUR_API_TOKEN_HERE",
"--baseUrl",
"http://127.0.0.1:6806"
]
}
}
}备注：如果全局安装，则可以使用 "command": "siyuan-mcp" 而不是 "command": "npx".
验证安装
配置后，重新启动MCP客户端（Cursor/Claude Desktop）并尝试：
- “列出我所有的思源笔记本”
- 搜索包含“项目计划”的文档
- “在我的工作笔记本中创建新的会议笔记”
- “显示最近修改的5个文档”
🛠️ 可用的MCP工具
配置后，您可以通过自然语言与思源进行交互。服务器提供15个基本工具：
🔍 搜索
- 统一搜索 -统一搜索工具：按内容、文件名、标签或任何组合进行搜索
📄 文档操作
- get_document_content -获取文档的降价内容
- 创建_文档 -创建新文档
- 附录_文档 -将内容附加到现有文档
- update_document -更新（覆盖）文档内容
- move_文档 -将一个或多个文档移动到新位置
- get_document_tree -获取具有指定深度的文档树结构
📅 每日笔记
- append_to_daily_note -添加到今天的每日笔记中（如果需要，会自动创建）
📚 笔记本管理
- list_notebooks -列出所有笔记本
- 获取最近更新的文档 -获取最近更新的文档
📸 快照管理
- create_snapshot -创建数据快照进行备份
- list_snapshots -列出可用快照
- rollback_to_snapshot -回滚到特定快照
🏷️ 标签管理
- list_all_tags -列出工作区中的所有唯一标签
- 支持按前缀过滤(prefix 参数） - 支持深度限制(depth 参数，从1开始，标签之间用 /)
- batch_replace_tag -批量替换或删除所有文档中的标签
使用示例
自然地问你的AI助手：
"List all my SiYuan notebooks"
"Search for documents about machine learning"
"Create a new document called 'Project Ideas' in my Work notebook"
"Show me the 10 most recently modified documents"
"Append 'Meeting notes: discussed Q4 goals' to today's daily note"
"Create a snapshot before I make major changes"
"What's the tree structure of my 'Projects' notebook?"
"Move document X to the root of my Work notebook"
"Move documents X and Y under document Z"📖 刀具参数参考
move_文档
将一个或多个文档移动到新位置。
参数：
from_ids（字符串\[\]）- 必需要移动的文档ID数组
- 对于单个文档，使用一个包含一个元素的数组： ["20210101000000-abc1234"] - 对于多个文档： ["20210101000000-abc1234", "20210102000000-def5678"]
to_parent_id（字符串）- 选项1：目标父文档ID。文档将作为子文档移动到此文档下。不能与一起使用to_notebook_root.to_notebook_root（字符串）- 选项2：目标笔记本ID。文档将被移动到此笔记本的根目录（顶层）。不能与一起使用to_parent_id.
重要提示： 您必须提供一个目的地： to_parent_id 或 to_notebook_root.
示例：
// Move single document to notebook root
{
from_ids: ["20210101000000-abc1234"],
to_notebook_root: "20210101000000-notebook1"
}
// Move multiple documents under another document
{
from_ids: ["20210101000000-abc1234", "20210102000000-def5678"],
to_parent_id: "20210103000000-parent99"
}batch_replace_tag
批量替换所有文档中出现的所有标记。
参数：
old_tag（字符串）- 必需.要替换的标签名称（不带#符号）new_tag（字符串）- 必需.新标记名称（不带#符号，使用空字符串删除）
示例：
// Replace tag
{
old_tag: "project",
new_tag: "work-project"
}
// Remove tag
{
old_tag: "deprecated",
new_tag: ""
}🔧 高级：用作TypeScript库
虽然主要设计为MCP服务器，但您也可以在自己的项目中将此包用作TypeScript库：
import { createSiyuanTools } from '@porkll/siyuan-mcp';
// Create an instance
const siyuan = createSiyuanTools('http://127.0.0.1:6806', 'your-token');
// Search operations
const files = await siyuan.searchByFileName('keyword', 10);
const blocks = await siyuan.searchByContent('content', 20);
// Document operations
const content = await siyuan.getFileContent(documentId);
await siyuan.createFile('notebookId', '/path/to/doc', '# Title\n\nContent');
await siyuan.appendToFile(documentId, 'New content');
await siyuan.overwriteFile(documentId, 'Replaced content');
// Daily note
await siyuan.appendToDailyNote('notebookId', 'Today I learned...');
// Notebook operations
const notebooks = await siyuan.listNotebooks();
// SQL queries
const results = await siyuan.search.query(`
SELECT * FROM blocks
WHERE type='d' AND content LIKE '%keyword%'
ORDER BY updated DESC
LIMIT 10
`);
// Direct API access
await siyuan.block.insertBlockAfter(blockId, 'New block content');
await siyuan.document.moveDocument(['doc1', 'doc2'], 'targetNotebookId');
const tree = await siyuan.document.getDocTree('notebookId', 2);类型定义
包含完整的TypeScript类型：
import type {
SiyuanConfig,
SiyuanApiResponse,
Block,
Notebook,
NotebookConf,
DocTreeNode,
SearchOptions
} from '@porkll/siyuan-mcp';💻 发展
设置
# Clone and install
git clone https://github.com/porkll/siyuan-mcp.git
cd siyuan-mcp
npm install
# Build
npm run build
# Watch mode (auto-rebuild)
npm run watch
# Lint
npm run lint
# Format
npm run format手动测试
# Start stdio server manually
npm run mcp:stdio -- --token YOUR_TOKEN --baseUrl http://127.0.0.1:6806
# Start HTTP server (for web clients)
npm run mcp:http -- --token YOUR_TOKEN --port 3000 --baseUrl http://127.0.0.1:6806🏗️ 建筑
siyuan-mcp/
├── src/ # Core TypeScript library
│ ├── api/ # SiYuan API clients
│ ├── types/ # Type definitions
│ └── utils/ # Helper utilities
├── mcp-server/ # MCP server implementation
│ ├── bin/ # CLI entry points
│ ├── core/ # MCP server core
│ ├── handlers/ # Tool handlers
│ └── transports/ # Stdio/HTTP transports
└── dist/ # Compiled JavaScript🔧 技术栈
- 语言：TypeScript 5.3+
- 运行时：Node.js 18+
- 模块系统：ES模块
- MCP-SDK：@modelcontextprotocol/sdk
- 协议：MCP（模型上下文协议）
❓ 常见问题解答
如何获取我的思源API代币？
- 打开思源纸币
- 转到“设置”→ 关于→ API代币
- 复制令牌
如何找到我的笔记本ID？
问你的MCP客户：“列出我所有的思源笔记本”，它会显示ID。
或者以编程方式：
const notebooks = await siyuan.listNotebooks();
console.log(notebooks.map(nb => `${nb.name}: ${nb.id}`));服务器不工作，我应该检查什么？
- 思源在跑步吗？（默认值：http://127.0.0.1:6806)
- 您的API令牌正确吗？
- 配置后是否重新启动了MCP客户端？
- 检查MCP客户端中的日志
我可以使用其他思源端口吗？
对！只需更新 baseUrl 参数：
"--baseUrl", "http://127.0.0.1:YOUR_PORT"这适用于远程思源实例吗？
对！点 baseUrl 到您的远程实例：
"--baseUrl", "http://your-server.com:6806"🤝 贡献
欢迎投稿！请随时提交问题和拉取请求。
📄 许可证
阿帕奇-2.0
🔗 相关项目
- 思源纸币 -思源纸币官方存储库
- 模型上下文协议 -MCP文件
- MCP TypeScript SDK -官方MCP SDK
🙏 致谢
该项目主要在人工智能的帮助下开发，并建立在优秀的 思源纸币 项目。