SiYuan MCP Server

一个为思源笔记（SiYuan）设计的 Model Context Protocol (MCP) 服务器，提供完整的 AI 集成和智能知识管理功能。

🌟 核心特性

笔记管理

• 笔记本操作: 创建、列表、打开、关闭、重命名、删除笔记本
• 文档管理: 创建、读取、更新、删除文档，支持批量操作
• 块操作: 创建、读取、更新、删除笔记块，支持批量操作
• 块属性: 设置和获取块属性，支持自定义属性管理

搜索功能

• 简单搜索: 快速关键词搜索
• 递归搜索: 深度内容挖掘，支持层级遍历
• 文档内搜索: 在指定文档中精确查找
• 批量读取: 高效批量读取多个文档

模板与渲染

• 模板渲染: 支持标准模板语法
• Sprig模板: 支持Sprig函数库的高级模板功能
• 动态内容: 基于模板生成格式化内容

导出功能

• Markdown导出: 导出为标准Markdown格式
• 多格式导出: 支持PDF、Word、HTML等多种格式
• 树状结构导出: 保留文档层级关系的JSON导出

资源管理

• 文件上传: 上传图片、文档等资源文件
• 资源列表: 列出文档中的所有资源
• 资源重命名: 重命名资源文件
• OCR识别: 图片文字识别功能

数据操作

• SQL查询: 执行SQL查询，支持复杂的数据检索
• 文件操作: 读取、写入、删除文件
• 文件列表: 列出目录中的文件

系统工具

• 时间获取: 获取当前真实时间，支持多种格式和时区
• 健康检查: 系统健康状态监控
• 端口发现: 自动发现思源笔记可用端口

AI 智能集成

• 智能工具选择: AI驱动的工具推荐和选择
• 使用场景指导: 详细的工具使用场景和示例
• 性能优化建议: 基于使用模式的优化建议
• 错误处理: 标准化的错误处理和重试机制

性能优化

• 缓存机制: 智能缓存提升响应速度
• 批量处理: 高效的批量数据操作
• 性能监控: 实时性能指标和统计
• 并发控制: 合理的并发请求管理

🚀 快速开始

1. 安装思源笔记

1. 下载安装包：https://github.com/siyuan-note/siyuan/releases
2. 启动思源笔记

2. 配置思源笔记

1. 启动思源笔记
2. 设置 → 关于 → API token
3. 复制API Token

3. 安装 MCP Server

从 npm 安装

npm install -g siyuan-mcp-server

从源码安装

git clone https://github.com/your-username/siyuan-mcp-server.git
cd siyuan-mcp-server
npm install
npm run build
npm link

4. 配置 MCP

在您的 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["siyuan-mcp-server"],
      "env": {
        "SIYUAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

注意:

• SIYUAN_API_URL 是可选的，如果不配置，系统会自动发现思源笔记的可用端口
• 如果需要指定端口，可以添加 "SIYUAN_API_URL": "http://127.0.0.1:6806"

5. 环境变量

• SIYUAN_API_TOKEN: 思源笔记 API Token（必需）
• SIYUAN_API_URL: 思源笔记 API 地址（可选，默认自动发现可用端口）

端口自动发现:

• 系统会自动扫描思源笔记的常用端口（6806, 6807, 6808）
• 如果思源笔记正在运行，系统会自动连接到正确的端口
• 如果自动发现失败，会尝试使用默认端口 6806
• 如需指定端口，可手动设置 SIYUAN_API_URL 环境变量

🛠️ 技术栈

• 运行时: Node.js 18+
• 语言: TypeScript
• 协议: Model Context Protocol (MCP)
• HTTP客户端: Axios
• 构建工具: TypeScript Compiler

📡 MCP 工具列表

📚 笔记本操作 (Notebook)

• list_notebooks - 列出所有笔记本
• open_notebook - 打开笔记本
• close_notebook - 关闭笔记本
• rename_notebook - 重命名笔记本
• remove_notebook - 删除笔记本

📄 文档操作 (Document)

• create_document - 创建新文档
• get_document - 获取文档内容
• update_document - 更新文档
• delete_document - 删除文档
• list_documents - 列出文档
• batch_read_all - 批量读取所有文档

🧱 块操作 (Block)

• create_block - 创建块
• get_block - 获取块
• update_block - 更新块
• delete_block - 删除块
• prepend_block - 在块前插入
• append_block - 在块后追加
• fold_block - 折叠块
• unfold_block - 展开块
• transfer_block_ref - 转移块引用
• set_block_attrs - 设置块属性
• get_block_attrs - 获取块属性
• batch_create_blocks - 批量创建块
• batch_update_blocks - 批量更新块
• batch_delete_blocks - 批量删除块

🔍 搜索操作 (Search)

• simple_search - 简单搜索
• recursive_search - 递归搜索
• search_in_document - 在文档中搜索

🎨 模板操作 (Template)

• render_template - 渲染模板
• render_sprig_template - 渲染Sprig模板

📤 导出操作 (Export)

• export_markdown - 导出为Markdown
• export_file - 导出为指定格式
• export_expand - 导出为树状结构

🖼️ 资源操作 (Assets)

• upload_asset - 上传资源文件
• list_assets - 列出资源文件
• rename_asset - 重命名资源文件
• ocr_asset - OCR识别图片

💾 SQL查询 (SQL)

• query_sql - 执行SQL查询

📁 文件操作 (File)

• read_file - 读取文件
• write_file - 写入文件
• delete_file - 删除文件
• list_files - 列出文件

⏰ 系统操作 (System)

• get_current_time - 获取当前真实时间

📖 使用示例

创建文档

// 创建新文档
await toolRegistry.execute('create_document', {
  notebook: 'notebook-id',
  path: '/path/to/document',
  title: '文档标题',
  content: '文档内容'
});

搜索内容

// 递归搜索
await toolRegistry.execute('recursive_search', {
  query: '关键词',
  notebook: 'notebook-id',
  maxDepth: 5
});

批量操作

// 批量创建块
await toolRegistry.execute('batch_create_blocks', {
  requests: [
    { content: '第一个块' },
    { content: '第二个块' }
  ]
});

获取时间

// 获取当前时间
await toolRegistry.execute('get_current_time', {
  format: 'iso',
  timezone: 'Asia/Shanghai'
});

导出文档

// 导出为Markdown
await toolRegistry.execute('export_markdown', {
  id: 'document-id'
});

🔧 开发

构建项目

npm run build

运行测试

npm test

代码检查

npm run lint

类型检查

npm run typecheck

🤝 贡献指南

欢迎贡献代码、报告问题或提出改进建议！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

感谢思源笔记团队提供优秀的笔记软件和 API 支持。

📮 联系方式

• 问题反馈: GitHub Issues
• 功能建议: GitHub Discussions