使用说明

项目简介

本项目 'siyuan-mcp-server' 是一个 Model Context Protocol (MCP) 服务器的实现，旨在作为大型语言模型（LLM）与思源笔记之间的桥梁。通过此服务器，LLM 客户端可以安全、可控地访问和操作存储在思源笔记中的知识库数据，从而实现更智能化的知识管理和应用。

主要功能点

知识库连接: 连接到您的思源笔记，使 LLM 能够访问您的个人知识库。
数据访问: 提供丰富的 API 接口，允许 LLM 读取和查询笔记内容、文档结构、属性信息等。
内容操作: 支持 LLM 创建、更新、删除和移动笔记块及文档，实现对知识库内容的编辑和管理。
资源管理: 允许 LLM 上传和管理思源笔记中的文件和资源。
高级查询: 支持 SQL 查询和全文搜索，使 LLM 能够进行复杂的数据检索。
功能扩展: 通过工具 (Tools) 机制，支持集成 Pandoc 文档转换、网络代理等外部功能。
模板渲染: 支持模板功能，可以根据思源笔记模板或 Sprig 模板动态生成内容。
通知提醒: 允许服务器向客户端推送消息通知。

安装步骤

安装 Node.js 和 pnpm：确保您的系统已安装 Node.js (>= 23.10.0) 和 pnpm。
安装依赖：在项目根目录下，打开终端并运行命令：
```
pnpm install
```

配置环境变量：设置 'SIYUAN_TOKEN' 环境变量，用于思源笔记 API 认证。您可以在思源笔记的 设置 - 关于 中找到 API 令牌。

Windows:

set SIYUAN_TOKEN=您的思源笔记API令牌

Linux/macOS:

export SIYUAN_TOKEN=您的思源笔记API令牌

服务器配置

对于 MCP 客户端（例如 Claude Desktop），您需要配置 MCP 服务器的启动命令。以下是一个 'claude_desktop_config.json' 的配置示例，用于连接 'siyuan-mcp-server'：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": [
        "-y",
        "@onigeya/siyuan-mcp-server"
      ],
      "env": {
        "SIYUAN_TOKEN": "您的思源笔记API令牌"
      }
    }
  }
}

配置参数说明:

'"siyuan"': 服务器名称，您可以自定义。
'"command": "npx"': 启动服务器的命令，这里使用 'npx' 执行 npm 包。
'"args": ["-y", "@onigeya/siyuan-mcp-server"]': 'npx' 命令的参数，指定运行 '@onigeya/siyuan-mcp-server' 包。'-y' 参数用于自动确认安装包。
'"env": { "SIYUAN_TOKEN": "您的思源笔记API令牌" }': 环境变量配置，将您的思源笔记 API 令牌设置为 'SIYUAN_TOKEN'。请务必替换 '"您的思源笔记API令牌"' 为您实际的令牌。

基本使用方法

启动服务器：在项目根目录下，打开终端并运行命令：

pnpm start

或者使用 Docker 运行：

docker run --rm -i -e SIYUAN_TOKEN=您的思源笔记API令牌 mcp/siyuan

在 MCP 客户端中使用：配置好 MCP 客户端后，客户端将通过 JSON-RPC 协议与 'siyuan-mcp-server' 通信。客户端可以使用 'executeCommand' 工具调用服务器提供的各种命令，例如：

查询笔记本列表:

{
  "type": "executeCommand",
  "params": {
    "type": "notebook.lsNotebooks"
  }
}

获取文档内容:

{
  "type": "executeCommand",
  "params": {
    "type": "file.getFile",
    "params": {
      "path": "/data/您的笔记本ID/您的文档路径.sy"
    }
  }
}

查看命令帮助:

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

您可以参考 命令列表 | Command List 章节和代码仓库中的 'src/tools/commands' 目录，了解所有可用的命令及其参数。

关键词