{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_bbwdy9952snp","handle":"siyuan-mcp-server","url":"https://wellknown.network/agents/siyuan-mcp-server","links":{"self":"https://wellknown.network/agents/siyuan-mcp-server/record.json","html":"https://wellknown.network/agents/siyuan-mcp-server","markdown":"https://wellknown.network/agents/siyuan-mcp-server/record.md","api":"https://wellknown.network/api/v1/agents/siyuan-mcp-server","status":"https://wellknown.network/api/v1/agents/siyuan-mcp-server/status","claim":"https://wellknown.network/agents/siyuan-mcp-server/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/siyuan-mcp-server/claim.json","badge":"https://wellknown.network/agents/siyuan-mcp-server/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/siyuan-mcp-server/history","tools":"https://wellknown.network/api/v1/agents/siyuan-mcp-server/tools"},"ard":{"identifier":"urn:air::server:siyuan-mcp-server","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"siyuan-mcp-server","summary":"思源笔记 MCP Server - 提供思源笔记API的MCP工具接口","description":"# 思源笔记 MCP 服务器 (官方 SDK 版)\n\n本项目提供了一个基于官方SDK构建的思源笔记 MCP (Model Context Protocol) 服务器。它允许 AI Agent 通过一套标准化的工具与您的思源笔记知识库进行交互。\n\n该服务器充当一座桥梁，将 MCP 的工具调用转换为对思源笔记 API 的请求，提供强大的读写能力，并内置统一的前台通知机制。\n\n## 为什么用MCP，不用Skill\n\n因为MCP可以控制Agent操作的权限和范围，例如可以将笔记中的敏感信息打码脱敏后返回，Agent接触不到真实的敏感信息。并且通过强制的通知机制，让Agent对笔记的所有操作透明化。\n\n而使用Skill的话，Agent会对笔记有100%的权限，能够读取所有源内容，并且可以对笔记做任意删除操作，有较高的的风险。并且Agent对笔记的操作审计只能依赖其自省，当Agent智能不足，或出现上下文迷失时，很容易出问题。\n\n当然想用Skill的方式操纵思源笔记也很简单，让Agent读一下`doc(read only)`目录下的API和数据结构文档，它就会明白如何使用官方的SDK对笔记进行增删查改。但总的来说我不推荐这么做，有数据隐私和安全风险。\n\n## 功能特性\n\n- **基于官方 SDK 构建**: 确保了兼容性并遵循最佳实践。\n- **`MCPServer` 集成**: 使用高级的 `MCPServer` 服务器，兼具简洁与强大。\n- **生命周期管理**: 通过 `lifespan` 机制安全地管理 `SiyuanAPI` 客户端的生命周期。\n- **装饰器驱动的工具**: 使用 `@mcp.tool()` 装饰器，工具定义清晰简洁。\n- **完整的读写能力**: 提供笔记本/文档/内容块的查询、创建、更新、移动等全流程操作。\n- **兼具高层与底层工具**: 同时提供易于使用的高级查询工具和功能强大的底层 `execute_sql` 工具，以实现最大灵活性。\n- **前台通知工具**: 提供 `push_message` 和 `push_error_message`，用于写操作的结果反馈与错误提示。\n- **敏感数据自动打码**: 自动检测并打码返回内容中的敏感信息（如 API 密钥、令牌、密码等），保护用户隐私和数据安全。\n\n## 环境要求\n\n- **Python 3.10+**（仅开发时需要，使用 uvx 运行时无需）\n- **uv**（推荐使用，用于 `uvx` 命令）\n- 思源笔记桌面客户端正在运行\n- 思源笔记 API Token（在思源笔记设置中获取）\n\n### 环境变量\n\n| 变量名 | 必填 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `SIYUAN_API_TOKEN` | 是 | - | 思源笔记 API Token |\n| `SIYUAN_API_URL` | 否 | `http://127.0.0.1:6806` | 思源笔记 API 地址，支持自定义远程地址 |\n\n### 安装 uv\n\n如果尚未安装 uv：\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# 或使用包管理器\npip install uv\n```\n\n## 安装与配置\n\n1.  **克隆仓库:**\n    ```bash\n    git clone <repository-url>\n    cd siyuan-mcp-server\n    ```\n\n2.  **安装依赖:**\n    我们推荐使用 `uv`。\n    ```bash\n    uv sync\n    ```\n\n## 如何运行\n\n### 方式一：使用 uvx（推荐，无需安装）\n\n这是最简单的方式，无需预先安装，`uvx` 会自动从 PyPI 下载并运行。\n\n**Claude Desktop 配置**:\n\n```json\n{\n  \"mcpServers\": {\n    \"siyuan\": {\n      \"command\": \"uvx\",\n      \"args\": [\"siyuan-mcp-server\"],\n      \"env\": {\n        \"SIYUAN_API_TOKEN\": \"your_token_here\",\n        \"SIYUAN_API_URL\": \"http://127.0.0.1:6806\"\n      }\n    }\n  }\n}\n```\n\n**指定…","publisher":{"name":"leolulu","url":null},"homepage":null,"repository":null,"version":"0.31.0","license":"MIT","protocols":["mcp"],"tags":["mcp"],"pricing":null,"endpoints":[{"url":"pypi:siyuan-mcp-server","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","license":"pypi","summary":"pypi","version":"pypi","description":"pypi","publisherName":"pypi"}},"derived":{"capabilities":[{"slug":"dev.version-control","name":"Version Control","confidence":0.791,"provenance":"derived"}],"categories":["dev"],"language":"zh"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"siyuan-mcp-server","registry":"pypi","observedAt":"2026-11-04T00:27:42.027Z","publishedAt":"2026-09-13T01:21:33.536140Z","latestVersion":"0.31.0"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"siyuan-mcp-server","url":"https://pypi.org/project/siyuan-mcp-server/","firstSeenAt":"2026-09-10T12:22:19.995Z","fetchedAt":"2026-11-04T00:27:03.233Z","normalizedAt":"2026-11-04T00:27:03.233Z"}]},"firstSeenAt":"2026-09-10T12:22:19.995Z","updatedAt":"2026-11-04T00:27:42.027Z"}