SiYuan Note MCP Server

一个 MCP 服务器实现，提供与思源笔记系统的集成，使 AI 模型能够访问和操作笔记数据。

功能特性 | Features

• 笔记本管理 | Notebook Management
• 文档操作 | Document Operations
• 内容块控制 | Block Control
• 文件和资源管理 | File and Asset Management
• SQL 查询支持 | SQL Query Support
• 属性管理 | Attribute Management
• 导出和转换 | Export and Conversion
• 系统功能 | System Functions

命令列表 | Command List

所有命令都支持使用 help 查询获取详细说明。例如：

{
  "type": "help",
  "params": {
    "type": "block.insertBlock"
  }
}

资源管理 | Asset Management

• assets.uploadAssets - 上传资源文件 | Upload assets

属性管理 | Attribute Management

• attr.setBlockAttrs - 设置块属性 | Set block attributes
• attr.getBlockAttrs - 获取块属性 | Get block attributes

内容块操作 | Block Operations

• block.insertBlock - 插入内容块 | Insert a block
• block.updateBlock - 更新内容块 | Update block content
• block.deleteBlock - 删除内容块 | Delete a block
• block.moveBlock - 移动内容块 | Move a block
• block.getBlockKramdown - 获取块的 Markdown 内容 | Get block Kramdown content

格式转换 | Format Conversion

• convert.pandoc - 使用 Pandoc 转换内容 | Convert content using Pandoc

导出功能 | Export Functions

• export.exportNotebook - 导出笔记本 | Export notebook
• export.exportDoc - 导出文档 | Export document

文件操作 | File Operations

• file.getFile - 获取文件内容 | Get file content
• file.putFile - 写入文件内容 | Put file content
• file.removeFile - 删除文件 | Remove file
• file.readDir - 读取目录内容 | List files in directory

文档树操作 | File Tree Operations

• filetree.createDocWithMd - 使用 Markdown 创建文档 | Create document with Markdown
• filetree.renameDoc - 重命名文档 | Rename document
• filetree.removeDoc - 删除文档 | Remove document
• filetree.moveDocs - 移动文档 | Move documents
• filetree.getHPathByPath - 获取文档可读路径 | Get document HPath by path
• filetree.getHPathByID - 通过 ID 获取文档可读路径 | Get document HPath by ID

网络代理 | Network Proxy

• network.forwardProxy - 网络请求代理 | Forward proxy request

笔记本管理 | Notebook Management

• notebook.lsNotebooks - 列出所有笔记本 | List all notebooks
• notebook.openNotebook - 打开笔记本 | Open notebook
• notebook.closeNotebook - 关闭笔记本 | Close notebook
• notebook.renameNotebook - 重命名笔记本 | Rename notebook
• notebook.createNotebook - 创建笔记本 | Create notebook
• notebook.removeNotebook - 删除笔记本 | Remove notebook
• notebook.getNotebookConf - 获取笔记本配置 | Get notebook configuration
• notebook.setNotebookConf - 设置笔记本配置 | Set notebook configuration

通知提醒 | Notifications

• notification.pushMsg - 发送消息通知 | Push message notification
• notification.pushErrMsg - 发送错误通知 | Push error message notification

查询功能 | Query Functions

• query.sql - 执行 SQL 查询 | Execute SQL query
• query.block - 通过 ID 查询块 | Query block by ID

搜索功能 | Search Functions

• search.fullTextSearch - 全文搜索 | Full text search

SQL 查询 | SQL Query

• sql.sql - 执行 SQL 查询 | Execute SQL query

系统功能 | System Functions

• system.getBootProgress - 获取启动进度 | Get boot progress
• system.getVersion - 获取系统版本 | Get system version
• system.getCurrentTime - 获取当前时间 | Get current time

模板功能 | Template Functions

• template.renderTemplate - 渲染模板 | Render template
• template.renderSprig - 渲染 Sprig 模板 | Render Sprig template

使用说明 | Usage

环境变量配置 | Environment Variables

服务器需要配置以下环境变量：

• SIYUAN_TOKEN - 思源笔记 API 令牌（必需）| SiYuan Note API token (required)
  • 在思源笔记设置 - 关于 中查看 | Check in SiYuan Note Settings - About
  • 用于 API 认证 | Used for API authentication

在 Claude Desktop 中使用 | Using in Claude Desktop

将以下配置添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": [
        "-y",
        "@onigeya/siyuan-mcp-server"
      ],
      "env": {
        "SIYUAN_TOKEN": "your-siyuan-token"
      }
    }
  }
}

本地运行 | Local Run

1. 安装依赖 | Install dependencies:

pnpm install

2. 设置环境变量 | Set environment variables:

# Windows
set SIYUAN_TOKEN=your-siyuan-token

# Linux/macOS
export SIYUAN_TOKEN=your-siyuan-token

3. 启动服务 | Start service:

pnpm start

Docker 运行 | Docker Run

docker run --rm -i \
  -e SIYUAN_TOKEN=your-siyuan-token \
  mcp/siyuan

构建 | Build

环境要求 | Requirements

• Node.js >= 23.10.0
• pnpm

本地构建 | Local Build

pnpm build

Docker 构建 | Docker Build

docker build -t mcp/siyuan .

许可证 | License

本项目基于 ISC 许可证发布。这意味着你可以自由使用、修改和分发本软件，但需要遵守 ISC 许可证的条款和条件。详细信息请参见项目仓库中的 LICENSE 文件。

相关资源 | Related Resources

• 思源笔记 | SiYuan Note
• Model Context Protocol
• 思源笔记 API 文档 | SiYuan Note API Documentation