SiYuan MCP Server
Enables AI assistants to create, read, update, and manage notes, documents, blocks, databases (attribute views), files, and more within a SiYuan Note instance via the SiYuan API.
Click on "Deploy 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 MCP Server create note titled 'Ideas' in my personal notebook"
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.
SiYuan MCP Server
English | 简体中文
Model Context Protocol (MCP) server for SiYuan Note.
Enable AI assistants to create, read, update, and manage your SiYuan notes directly.
Features
Notebook Management — Create, rename, open/close, and organize notebooks
Document Operations — List, create, edit, move, and delete documents
Block-level Editing — Insert, prepend, append, update, delete, move, fold/unfold, and query content blocks
Database (Attribute View) — Create tables, add/update/delete rows and columns
Search & Query — Full-text search and SQL queries
File Operations — Upload, download, list, and manage assets
Export & Conversion — Export Markdown, Pandoc conversion
Related MCP server: SiYuan Note MCP Server
Installation
Requirements
Node.js >= 18
SiYuan Note running with API enabled
SiYuan API Token (Settings → About → API Token)
NPM
npm install -g siyuan-mcp-serverNPX (no install)
npx siyuan-mcp-serverConfiguration
Set the SIYUAN_TOKEN environment variable to your SiYuan API token.
Optional: set SIYUAN_API_URL (default: http://localhost:6806).
Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"siyuan": {
"command": "npx",
"args": ["-y", "siyuan-mcp-server"],
"env": {
"SIYUAN_TOKEN": "your-api-token"
}
}
}
}Available Commands
All commands are exposed both as standalone MCP tools and via the executeCommand dispatcher.
Namespace | Description |
| Database (Attribute View) operations |
| Block-level CRUD, move, fold/unfold, query children |
| Document list/create/rename/remove/move |
| Notebook management |
| File read/write/list |
| Full-text search |
| SQL queries and block lookup |
| Block attributes |
| Asset upload |
| Export notebook / document |
| Pandoc conversion |
| System info |
| Push messages |
| Template rendering |
| SQL queries |
| Forward proxy |
Notebook Commands
Command | Description |
| List all notebooks |
| Open a closed notebook |
| Close a notebook |
| Rename a notebook |
| Create a new notebook |
| Remove a notebook |
| Get notebook configuration |
| Set notebook configuration |
Document Commands
Command | Description |
| List documents in a notebook by path |
| Create a document with Markdown content |
| Rename a document |
| Rename a document by ID |
| Remove a document |
| Remove a document by ID |
| Move documents |
| Move documents by ID |
| Get human-readable path by path |
| Get human-readable path by ID |
Block Commands
Command | Description |
| Insert a block after a specific block |
| Prepend blocks to a parent block |
| Append blocks to a parent block |
| Update block content |
| Delete a block |
| Move a block |
| Get block Kramdown content |
| Get child blocks of a parent block |
| Fold a block |
| Unfold a block |
Database Operations (Attribute View)
Command | Description |
| Create a new database table |
| View database structure and rows |
| Add rows to a database |
| Update row values |
| Delete rows |
| Add a column |
| Remove a column |
| Update a single cell |
Search & Query
Command | Description |
| Full-text search across notes |
| Execute SQL query on the database |
| Query a single block by ID |
File & Asset Commands
Command | Description |
| Get file content |
| Upload/write a file |
| Remove a file |
| List files in a directory |
| Upload asset files |
Other Commands
Command | Description |
| Set block attributes |
| Get block attributes |
| Export notebook |
| Export document |
| Convert files via Pandoc |
| Get boot progress |
| Get SiYuan version |
| Get server current time |
| Push a notification message |
| Push an error message |
| Render a template |
| Render a Sprig template |
| Execute SQL query |
| Forward HTTP request via proxy |
MCP Tools
In addition to executeCommand, the following standalone MCP tools are registered for direct LLM discoverability:
queryCommands— List available commandsexecuteCommand— Execute any command by namehelp— Get detailed help for a specific commandav_createAttributeView/av_getAttributeView/av_addRow/av_updateRow/av_deleteRow/av_addColumn/av_removeColumn/av_updateCell
Development
npm install
npm run build
npm test
npm run devReinstalling after updates
NPX users: No action needed —
npxalways fetches the latest published version.NPM global install: Run
npm install -g siyuan-mcp-serveragain to upgrade.Local source / development: Run
npm run buildafter pulling changes.
Attribution
This project is based on the original siyuan-mcp-server by Fromsko, which in turn builds upon earlier work by onigeya.
Significant modifications and enhancements have been made, including:
Database (Attribute View) creation and full CRUD support
Fixed
file.getFileandfile.putFilecommandsIndependent MCP tool registration for better LLM discoverability
Added
filetree.listDocsByPath,block.prependBlock,block.appendBlock,block.getChildBlocks,block.foldBlock,block.unfoldBlockAdded
filetree.removeDocByID,filetree.renameDocByID,filetree.moveDocsByIDAdded
export.exportNotebook,system.getBootProgress,notification.pushErrMsg,template.renderSprigAV blockID-to-avID auto-resolution and SQL fallback for robust database access
Known API Behaviors
filetree.createDocWithMd: Does not overwrite existing documents when the samepathis used repeatedly.block.updateBlock: Replaces the content of a single block, not the entire document. To rewrite a whole document, delete its child blocks and append new content.filetree.removeDoc: May return success while the document remains visible due to SiYuan's internal index/cache. Usefiletree.removeDocByIDas a more reliable alternative when you have the document ID.
License
MIT
Available Tools
11 toolsav_addColumnAdd Column to SiYuan DatabaseB
Add a column to an existing database
Inputs: avID (required), name (required), type (required), options, +1 more.
av_addRowAdd Rows to SiYuan DatabaseC
Add rows to an existing database
Inputs: avID (required), rows (required).
av_createAttributeViewCreate SiYuan DatabaseB
Create a new database (Attribute View) in a SiYuan document
Inputs: name (required), docID (required), notebook (required), rows, +2 more.
av_deleteRowDelete Rows from SiYuan DatabaseC
Delete rows from a database
Inputs: avID (required), rowIDs (required).
av_getAttributeViewGet SiYuan DatabaseA
Get database (Attribute View) structure and data
Inputs: avID (required), page, viewID, pageSize.
av_removeColumnRemove Column from SiYuan DatabaseC
Remove a column from a database
Inputs: avID (required), keyID (required).
av_updateCellUpdate SiYuan Database CellB
Update a single cell value
Inputs: avID (required), rowID (required), columnName (required), value.
av_updateRowUpdate SiYuan Database RowC
Update values in a database row
Inputs: avID (required), rowID (required), values (required).
executeCommandD
执行指定的命令
Inputs: type (required), params.
helpB
获取命令的帮助信息
Inputs: type (required).
queryCommandsA
查询可用的命令列表
Inputs: type, namespace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools are clearly distinct: each av_* tool targets a specific operation on Attribute Views (CRUD for rows, columns, and views). The generic command tools (executeCommand, queryCommands, help) are also separate, though executeCommand could potentially overlap with the others in vague ways. Minor confusion exists between av_updateRow and av_updateCell, but descriptions make the distinction clear.
The av_* tools follow a consistent verb_noun pattern (e.g., av_addRow, av_deleteRow, av_createAttributeView), but the generic tools (executeCommand, queryCommands, help) break this pattern. Mixed prefixes and lack of uniform style across the server result in moderate inconsistency.
With 11 tools, the count is well within the ideal 3-15 range. Each tool serves a distinct purpose, and the set is neither bloated nor too sparse for the stated domain of Attribute View management plus command utilities.
The Attribute View lifecycle covers create, read, and update operations for structure and data, including row and column management. The only obvious gap is the lack of a delete view tool (av_deleteAttributeView), which means users cannot fully remove an Attribute View through this server. Minor gaps like renaming columns are also absent, but agents can work around these.
Maintenance
Related MCP Connectors
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.
Read, search and edit your Sidenote notepads, whiteboards and images with your sync key.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables interaction with SiYuan Note through its API for comprehensive note management. Supports searching, creating, editing documents, managing notebooks, and daily notes operations through natural language commands.15Apache 2.0
- AlicenseCqualityCmaintenanceEnables AI assistants to interact with SiYuan Note for comprehensive notebook management, document editing, and block-level content operations. It supports advanced features like full-text search and SQL queries via secure API integration.334 npm40ISC
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with SiYuan Note through its API, supporting notebook and document management, block operations, search, file operations, and more.69102 npm75MIT
- AlicenseBqualityDmaintenanceEnables AI models to interact with SiYuan Note systems, allowing management of notebooks, documents, blocks, files, and more through natural language.3ISC