siyuan-mcp-server

# 思源笔记 MCP 服务器 (官方 SDK 版) 本项目提供了一个基于官方SDK构建的思源笔记 MCP (Model Context Protocol) 服务器。它允许 AI Agent 通过一套标准化的工具与您的思源笔记知识库进行交互。 该服务器充当一座桥梁，将 MCP 的工具调用转换为对思源笔记 API 的请求，提供强大的读写能力，并内置统一的前台通知机制。 ## 为什么用MCP，不用Skill 因为MCP可以控制Agent操作的权限和范围，例如可以将笔记中的敏感信息打码脱敏后返回，Agent接触不到真实的敏感信息。并且通过强制的通知机制，让Agent对笔记的所有操作透明化。 而使用Skill的话，Agent会对笔记有100%的权限，能够读取所有源内容，并且可以对笔记做任意删除操作，有较高的的风险。并且Agent对笔记的操作审计只能依赖其自省，当Agent智能不足，或出现上下文迷失时，很容易出问题。 当然想用Skill的方式操纵思源笔记也很简单，让Agent读一下`doc(read only)`目录下的API和数据结构文档，它就会明白如何使用官方的SDK对笔记进行增删查改。但总的来说我不推荐这么做，有数据隐私和安全风险。 ## 功能特性 - **基于官方 SDK 构建**: 确保了兼容性并遵循最佳实践。 - **`MCPServer` 集成**: 使用高级的 `MCPServer` 服务器，兼具简洁与强大。 - **生命周期管理**: 通过 `lifespan` 机制安全地管理 `SiyuanAPI` 客户端的生命周期。 - **装饰器驱动的工具**: 使用 `@mcp.tool()` 装饰器，工具定义清晰简洁。 - **完整的读写能力**: 提供笔记本/文档/内容块的查询、创建、更新、移动等全流程操作。 - **兼具高层与底层工具**: 同时提供易于使用的高级查询工具和功能强大的底层 `execute_sql` 工具，以实现最大灵活性。 - **前台通知工具**: 提供 `push_message` 和 `push_error_message`，用于写操作的结果反馈与错误提示。 - **敏感数据自动打码**: 自动检测并打码返回内容中的敏感信息（如 API 密钥、令牌、密码等），保护用户隐私和数据安全。 ## 环境要求 - **Python 3.10+**（仅开发时需要，使用 uvx 运行时无需） - **uv**（推荐使用，用于 `uvx` 命令） - 思源笔记桌面客户端正在运行 - 思源笔记 API Token（在思源笔记设置中获取） ### 环境变量 | 变量名 | 必填 | 默认值 | 说明 | |--------|------|--------|------| | `SIYUAN_API_TOKEN` | 是 | - | 思源笔记 API Token | | `SIYUAN_API_URL` | 否 | `http://127.0.0.1:6806` | 思源笔记 API 地址，支持自定义远程地址 | ### 安装 uv 如果尚未安装 uv： ```bash # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 或使用包管理器 pip install uv ``` ## 安装与配置 1. **克隆仓库:** ```bash git clone <repository-url> cd siyuan-mcp-server ``` 2. **安装依赖:** 我们推荐使用 `uv`。 ```bash uv sync ``` ## 如何运行 ### 方式一：使用 uvx（推荐，无需安装） 这是最简单的方式，无需预先安装，`uvx` 会自动从 PyPI 下载并运行。 **Claude Desktop 配置**: ```json { "mcpServers": { "siyuan": { "command": "uvx", "args": ["siyuan-mcp-server"], "env": { "SIYUAN_API_TOKEN": "your_token_here", "SIYUAN_API_URL": "http://127.0.0.1:6806" } } } } ``` **指定…