leolulu/siyuan-mcp-server

Developer tools

This page was translated automatically. Technical details may differ from the original. View the original

11 stars 5 forks Quality 80 Trend 26MIT

Repository Install

MCP server for turning Siyuan into an AI-native, automation-ready knowledge base.

Overview

本项目提供了一个基于官方SDK构建的思源笔记 MCP (Model Context Protocol) 服务器。它允许 AI Agent 通过一套标准化的工具与您的思源笔记知识库进行交互。该服务器充当一座桥梁，将 MCP 的工具调用转换为对思源笔记 API 的请求，提供强大的读写能力，并内置统一的前台通知机制。因为MCP可以控制Agent操作的权限和范围，例如可以将笔记中的敏感信息打码脱敏后返回，Agent接触不到真实的敏感信息。并且通过强制的通知机制，让Agent对笔记的所有操作透明化。而使用Skill的话，Agent会对笔记有100%的权限，能够读取所有源内容，并且可以对笔记做任意删除操作，有较高的的风险。并且Agent对笔记的操作审计只能依赖其自省，当Agent智能不足，或出现上下文迷失时，很容易出问题。当然想用Skill的方式操纵思源笔记也很简单，让Agent读一下doc(read only)目录下的API和数据结构文档，它就会明白如何使用官方的SDK对笔记进行增删查改。但总的来说我不推荐这么做，有数据隐私和安全风险。 - : 确保了兼容性并遵循最佳实践。 - : 使用高级的 MCPServer 服务器，兼具简洁与强大。 - : 通过 lifespan 机制安全地管理 SiyuanAPI 客户端的生命周期。 - : 使用 @mcp.tool() 装饰器，工具定义清晰简洁。 - : 提供笔记本/文档/内容块的查询、创建、更新、移动等全流程操作。 - : 同时提供易于使用的高级查询工具和功能强大的底层 execute_sql 工具，以实现最大灵活性。 - : 提供 push_message 和 push_error_message，用于写操作的结果反馈与错误提示。 - : 自动检测并打码返回内容中的敏感信息（如 API 密钥、令牌、密码等），保护用户隐私和数据安全。 - （仅开发时需要，使用 uvx 运行时无需） - （推荐使用，用于 uvx 命令） - 思源笔记桌面客户端正在运行 - 思源笔记 API Token（在思源笔记设置中获取） : - ✅ 无需预先安装包 - ✅ 自动版本管理 - ✅ 隔离的临时环境 - ✅ 自动依赖管理 - ✅ 快速启动（利用 uv 的缓存）

Install

uvx siyuan-mcp-server

New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "siyuan": {
      "command": "uvx",
      "args": ["siyuan-mcp-server"],
      "env": {
        "SIYUAN_API_TOKEN": "your_token_here",
        "SIYUAN_API_URL": "http://127.0.0.1:6806"
      }
    }
  }
}