SiYuan MCP Server

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

🌟 核心特性

笔记管理

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

搜索功能

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

模板与渲染

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

导出功能

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

资源管理

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

数据操作

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

系统工具

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

AI 智能集成

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

性能优化

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

🚀 快速开始

1. 安装思源笔记

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

2. 配置思源笔记

启动思源笔记
设置 → 关于 → API token
复制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

🤝 贡献指南

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

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

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

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

📮 联系方式

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

SiYuan MCP Server

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

🌟 核心特性

笔记管理

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

搜索功能

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

模板与渲染

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

导出功能

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

资源管理

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

数据操作

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

系统工具

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

AI 智能集成

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

性能优化

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

🚀 快速开始

1. 安装思源笔记

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

2. 配置思源笔记

启动思源笔记
设置 → 关于 → API token
复制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

🤝 贡献指南

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

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

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

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

📮 联系方式

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