SiYuan MCP server

SiYuan Note MCP Server is an implementation that bridges AI models with the SiYuan Note system, allowing models to interact with and manipulate your notes data. This server provides a comprehensive set of commands for managing notebooks, documents, content blocks, and more through the Model Context Protocol (MCP).

Installation

Using NPX (Easiest Method)

You can run the server directly with npx:

npx -y @onigeya/siyuan-mcp-server

Make sure to set the required environment variable:

# Windows
set SIYUAN_TOKEN=your-siyuan-token

# Linux/macOS
export SIYUAN_TOKEN=your-siyuan-token

Installing Locally

1. Install dependencies:

pnpm install

2. Set environment variables:

# Windows
set SIYUAN_TOKEN=your-siyuan-token

# Linux/macOS
export SIYUAN_TOKEN=your-siyuan-token

3. Start the service:

pnpm start

Using Docker

docker run --rm -i \
  -e SIYUAN_TOKEN=your-siyuan-token \
  mcp/siyuan

Using with Claude Desktop

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": [
        "-y",
        "@onigeya/siyuan-mcp-server"
      ],
      "env": {
        "SIYUAN_TOKEN": "your-siyuan-token"
      }
    }
  }
}

Usage

The MCP server provides various commands to interact with SiYuan Note. All commands support detailed documentation through the help command.

Getting Help

You can get detailed information about any command using:

{
  "type": "help",
  "params": {
    "type": "command.name"
  }
}

For example:

{
  "type": "help",
  "params": {
    "type": "block.insertBlock"
  }
}

Command Categories

Notebook Management

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

Document Operations

• filetree.createDocWithMd - Create document with Markdown
• filetree.renameDoc - Rename document
• filetree.removeDoc - Remove document
• filetree.moveDocs - Move documents
• filetree.getHPathByPath - Get document HPath by path
• filetree.getHPathByID - Get document HPath by ID
• export.exportDoc - Export document
• export.exportNotebook - Export notebook

Block Operations

• block.insertBlock - Insert a new block
• block.updateBlock - Update block content
• block.deleteBlock - Delete a block
• block.moveBlock - Move a block
• block.getBlockKramdown - Get block Kramdown content
• query.block - Query block by ID

Asset and File Management

• assets.uploadAssets - Upload assets
• file.getFile - Get file content
• file.putFile - Put file content
• file.removeFile - Remove a file
• file.readDir - List files in directory

Search and Query

• query.sql - Execute SQL query
• sql.sql - Execute SQL query (alternative)
• search.fullTextSearch - Full text search

Attribute Management

• attr.setBlockAttrs - Set block attributes
• attr.getBlockAttrs - Get block attributes

Format Conversion and Templates

• convert.pandoc - Convert content using Pandoc
• template.renderTemplate - Render template
• template.renderSprig - Render Sprig template

System Functions

• system.getBootProgress - Get boot progress
• system.getVersion - Get system version
• system.getCurrentTime - Get current time
• notification.pushMsg - Push message notification
• notification.pushErrMsg - Push error message notification
• network.forwardProxy - Forward proxy request

Environment Variables

The server requires the following environment variable:

• SIYUAN_TOKEN - SiYuan Note API token (required)
  • You can find this token in SiYuan Note Settings - About
  • Used for API authentication

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "siyuan" '{"command":"npx","args":["-y","@onigeya/siyuan-mcp-server"],"env":{"SIYUAN_TOKEN":"your-siyuan-token"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "siyuan": {
            "command": "npx",
            "args": [
                "-y",
                "@onigeya/siyuan-mcp-server"
            ],
            "env": {
                "SIYUAN_TOKEN": "your-siyuan-token"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "siyuan": {
            "command": "npx",
            "args": [
                "-y",
                "@onigeya/siyuan-mcp-server"
            ],
            "env": {
                "SIYUAN_TOKEN": "your-siyuan-token"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect