Siyuan MCP

思源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 命令将在全球范围内可用。

🔧 配置

先决条件

1. 获取您的思源API代币：

- 打开思源纸币 - 转到“设置”→ 关于→ API代币 - 复制令牌

1. 确保思源正在运行：

- 默认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代币？

1. 打开思源纸币
2. 转到“设置”→ 关于→ API代币
3. 复制令牌

如何找到我的笔记本ID？

问你的MCP客户：“列出我所有的思源笔记本”，它会显示ID。

或者以编程方式：

const notebooks = await siyuan.listNotebooks();
console.log(notebooks.map(nb => `${nb.name}: ${nb.id}`));

服务器不工作，我应该检查什么？

1. 思源在跑步吗？（默认值：http://127.0.0.1:6806)
2. 您的API令牌正确吗？
3. 配置后是否重新启动了MCP客户端？
4. 检查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

🙏 致谢

该项目主要在人工智能的帮助下开发，并建立在优秀的 思源纸币 项目。