The SiYuan Note MCP Server lets AI assistants directly control SiYuan Note via 50+ tools across 12 categories:
📓 Notebook management – Create, delete, rename, and configure notebooks
📄 Document operations – Create, delete, move, and rename documents (with hpath auto-resolution)
🧱 Block editing – Insert, update, delete, move, collapse, and expand content blocks
🔍 Search & Query – Full-text search, SQL queries, and transaction refresh
📎 Attributes – Get and set block attributes
📁 File system – Read, write, delete, rename files, and list directories
📋 Templates – Render templates with Sprig support
📤 Export – Export documents as Markdown or resource packages
🔄 Conversion – Pandoc format conversion
🔔 Notifications – Push messages/notifications
🌐 Network – Forward proxy requests
⚙️ System – Query version, startup progress, and current time
Key meta-tools include executeCommand (run any SiYuan command), queryCommands (discover available commands), and help (get detailed command documentation).
Provides a comprehensive set of tools for interacting with SiYuan Note, enabling management of notebooks, documents, and content blocks, as well as full-text search, SQL querying, and template rendering.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SiYuan Note MCP Server search my notes for 'machine learning' and summarize the key points"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
让 AI 助手直接操作思源笔记的 Model Context Protocol 服务器
项目 | 版本 |
思源笔记 | >= 3.0.0（已验证 3.7.1） |
SiYuan API | docs/API.md（50 个非 Database 端点） |
Node.js | >= 18.0.0 |
MCP SDK | @modelcontextprotocol/sdk ^1.8.0 |
Related MCP server: SiYuan MCP Server
# 直接运行
SIYUAN_TOKEN=your-api-token npx @fromsko/siyuan-mcp-server
# 全局安装
npm install -g @fromsko/siyuan-mcp-server
SIYUAN_TOKEN=your-api-token siyuan-mcp-server环境变量 | 必需 | 说明 | 默认值 |
| ✅ | 思源笔记 API Token（设置 → 关于） | — |
| ❌ | 思源 API 地址 |
|
如果你是 AI 助手，请将以下配置添加到你的 MCP 客户端配置中：
{
"mcpServers": {
"siyuan": {
"command": "npx",
"args": ["-y", "@fromsko/siyuan-mcp-server"],
"env": {
"SIYUAN_TOKEN": "<用户提供的 API Token>",
"SIYUAN_API_URL": "http://localhost:6806"
}
}
}
}配置文件位置：
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）
Cursor: .cursor/mcp.json
配置完成后重启客户端，即可使用 50 个思源笔记操作工具（笔记本管理、文档操作、块级编辑、全文搜索、SQL 查询等）。
类别 | 命令空间 | 端点数 | 能力 |
📓 笔记本 |
| 8 | 创建/删除/重命名/配置 |
📄 文档 |
| 11 | 创建/删除/移动/重命名（支持 hpath 自动解析） |
🧱 块操作 |
| 11 | 插入/更新/删除/移动/折叠/展开 |
🔍 搜索 |
| 3 | 全文搜索/SQL 查询/事务刷新 |
📎 属性 |
| 2 | 设置/获取块属性 |
📁 文件 |
| 5 | 读写/删除/重命名/列目录 |
📋 模板 |
| 2 | 渲染模板/Sprig |
📤 导出 |
| 2 | 导出 Markdown/导出资源包 |
🔄 转换 |
| 1 | Pandoc 格式转换 |
🔔 通知 |
| 2 | 推送消息 |
🌐 网络 |
| 1 | 正向代理 |
⚙️ 系统 |
| 3 | 版本/启动进度/当前时间 |
git clone https://github.com/Fromsko/siyuan-mcp-server.git
cd siyuan-mcp-server
npm install && npm run build && npm test详细开发文档：
文档 | 说明 |
开发指南、项目结构、添加端点流程 | |
MCP 使用指南 | |
官方 SiYuan API 文档 | |
LLM 导向的项目简介 | |
提交规范和开发约束 |
无法连接思源笔记 → 检查：思源是否运行、Token 是否正确、端口是否正确（默认 6806）
命令执行失败 → 确认笔记本/文档存在、Token 权限足够
连接远程思源 → 设置 SIYUAN_API_URL=http://your-server:6806
ISC — 详见 LICENSE
执行指定的命令
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | 命令类型 | |
| params | No | 命令参数 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It fails to mention side effects, authentication needs, error handling, or any constraints. It simply states 'execute', which is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no superfluous content. It is concise, but the extreme brevity sacrifices substance, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of command execution (with nested params) and no output schema, the description is severely incomplete. It omits return values, error conditions, and behavioral details, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'type' and 'params' parameters. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline expectation for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '执行指定的命令' (Execute the specified command) essentially restates the tool name 'executeCommand', making it a tautology. It gives no scope or distinction from sibling tools like 'queryCommands' or 'help'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, what types of commands are supported, or any prerequisites. The usage context is only implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取命令的帮助信息
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | 命令类型 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose behavioral traits such as read-only nature, potential side effects, or rate limits. It is likely a read operation but not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Appropriate length for a simple tool; front-loaded with the key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does not explain what the help output contains. Lacks context on relationship to siblings. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a basic description for the 'type' parameter. The tool description adds no additional meaning beyond the schema, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose: getting help information for commands. It is clear and specific, but does not differentiate from sibling tools like queryCommands or executeCommand.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询可用的命令列表
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | 命令名称过滤 | |
| namespace | No | 命令命名空间过滤 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral transparency. It only indicates a query operation, but fails to disclose aspects like idempotency, authentication needs, or rate limits. The minimal description does not sufficiently inform the agent of behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, fitting the tool's simplicity. No unnecessary words, and it is appropriately front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description is incomplete. It does not explain the return format, any constraints, or how to interpret results. For a tool with two optional parameters and siblings, more contextual information would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, with both parameters described in the schema. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: querying the list of available commands. It distinguishes from siblings 'executeCommand' and 'help' by focusing on listing rather than execution or assistance. However, the term 'available' could be more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'executeCommand' or 'help'. The description does not mention context or exclusion criteria, leaving the agent without direction on selecting the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: executeCommand runs a command, help retrieves help information, and queryCommands lists available commands. There is no overlap in functionality.
Tools use camelCase naming, but 'help' is a single word while others follow a verb_noun pattern. This minor inconsistency is acceptable but not perfectly uniform.
With only 3 tools, the server seems underdeveloped for a note-taking application. The tools are limited to command execution and help, lacking any note-specific operations.
The tool set is incomplete for a note server; there are no tools for creating, reading, updating, or deleting notes. The server focuses on generic command execution rather than note management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI access to your aNotepad online notes: read, search, write, and organize via 22 tools.
Create, search, and update notes in an xNotepad AI notebook, with semantic search and AI Q&A.
Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.
Securely search, create, and organize your Mem notes and collections from AI assistants.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Fromsko/siyuan-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
