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

Installation

Requirements

• Node.js >= 18
• SiYuan Note running with API enabled
• SiYuan API Token (Settings → About → API Token)

NPM

npm install -g siyuan-mcp-server

NPX (no install)

npx siyuan-mcp-server

Configuration

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
av.*	Database (Attribute View) operations
block.*	Block-level CRUD, move, fold/unfold, query children
filetree.*	Document list/create/rename/remove/move
notebook.*	Notebook management
file.*	File read/write/list
search.*	Full-text search
query.*	SQL queries and block lookup
attr.*	Block attributes
assets.*	Asset upload
export.*	Export notebook / document
convert.*	Pandoc conversion
system.*	System info
notification.*	Push messages
template.*	Template rendering
sql.*	SQL queries
network.*	Forward proxy

Notebook Commands

Command	Description
notebook.lsNotebooks	List all notebooks
notebook.openNotebook	Open a closed notebook
notebook.closeNotebook	Close a notebook
notebook.renameNotebook	Rename a notebook
notebook.createNotebook	Create a new notebook
notebook.removeNotebook	Remove a notebook
notebook.getNotebookConf	Get notebook configuration
notebook.setNotebookConf	Set notebook configuration

Document Commands

Command	Description
filetree.listDocsByPath	List documents in a notebook by path
filetree.createDocWithMd	Create a document with Markdown content
filetree.renameDoc	Rename a document
filetree.renameDocByID	Rename a document by ID
filetree.removeDoc	Remove a document
filetree.removeDocByID	Remove a document by ID
filetree.moveDocs	Move documents
filetree.moveDocsByID	Move documents by ID
filetree.getHPathByPath	Get human-readable path by path
filetree.getHPathByID	Get human-readable path by ID

Block Commands

Command	Description
block.insertBlock	Insert a block after a specific block
block.prependBlock	Prepend blocks to a parent block
block.appendBlock	Append blocks to a parent block
block.updateBlock	Update block content
block.deleteBlock	Delete a block
block.moveBlock	Move a block
block.getBlockKramdown	Get block Kramdown content
block.getChildBlocks	Get child blocks of a parent block
block.foldBlock	Fold a block
block.unfoldBlock	Unfold a block

Database Operations (Attribute View)

Command	Description
av.createAttributeView	Create a new database table
av.getAttributeView	View database structure and rows
av.addRow	Add rows to a database
av.updateRow	Update row values
av.deleteRow	Delete rows
av.addColumn	Add a column
av.removeColumn	Remove a column
av.updateCell	Update a single cell

Search & Query

Command	Description
search.fullTextSearch	Full-text search across notes
query.sql	Execute SQL query on the database
query.block	Query a single block by ID

File & Asset Commands

Command	Description
file.getFile	Get file content
file.putFile	Upload/write a file
file.removeFile	Remove a file
file.readDir	List files in a directory
assets.uploadAssets	Upload asset files

Other Commands

Command	Description
attr.setBlockAttrs	Set block attributes
attr.getBlockAttrs	Get block attributes
export.exportNotebook	Export notebook
export.exportDoc	Export document
convert.pandoc	Convert files via Pandoc
system.getBootProgress	Get boot progress
system.getVersion	Get SiYuan version
system.getCurrentTime	Get server current time
notification.pushMsg	Push a notification message
notification.pushErrMsg	Push an error message
template.renderTemplate	Render a template
template.renderSprig	Render a Sprig template
sql.sql	Execute SQL query
network.forwardProxy	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 commands
• executeCommand — Execute any command by name
• help — Get detailed help for a specific command
• av_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 dev

Reinstalling after updates

• NPX users: No action needed — npx always fetches the latest published version.
• NPM global install: Run npm install -g siyuan-mcp-server again to upgrade.
• Local source / development: Run npm run build after 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.getFile and file.putFile commands
• Independent MCP tool registration for better LLM discoverability
• Added filetree.listDocsByPath, block.prependBlock, block.appendBlock, block.getChildBlocks, block.foldBlock, block.unfoldBlock
• Added filetree.removeDocByID, filetree.renameDocByID, filetree.moveDocsByID
• Added export.exportNotebook, system.getBootProgress, notification.pushErrMsg, template.renderSprig
• AV blockID-to-avID auto-resolution and SQL fallback for robust database access

Known API Behaviors

• filetree.createDocWithMd: Does not overwrite existing documents when the same path is 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. Use filetree.removeDocByID as a more reliable alternative when you have the document ID.

License

MIT