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.

Notebook Commands

Document Commands

Block Commands

Database Operations (Attribute View)

Search & Query

File & Asset Commands

Other Commands

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