Skip to main content
Glama
SiYuan MCP Server

SiYuan MCP Server

by rexding97

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-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

Available Tools

11 tools
av_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

    B3/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables 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.
      15
      Apache 2.0
    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      3
      34 npm
      40
      ISC
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to interact with SiYuan Note through its API, supporting notebook and document management, block operations, search, file operations, and more.
      69
      102 npm
      75
      MIT