SiYuan

You operate a Model Context Protocol (MCP) server that exposes the full SiYuan Note API over a lightweight, script-driven interface. This server lets you connect AI tools and clients to SiYuan Note to perform reads, writes, and management tasks in notebooks, documents, blocks, and more, with secure token-based access and asynchronous processing for high performance.

How to use

You run the MCP server locally or in your environment and connect MCP clients to it. The server accepts calls to a complete set of SiYuan Note APIs, enabling you to manage notebooks, documents, blocks, files, templates, and exports. Ensure your MCP client is configured to point to the server address and uses a valid API token.

Typical usage patterns include starting the server, configuring a client with the connection details, and then issuing requests such as listing notebooks, creating documents, inserting or updating blocks, running SQL queries, and exporting content. All operations are performed through the MCP protocol, which standardizes how AI tools interact with SiYuan Note.

How to install

Prerequisites: You need Node.js version 18 or newer and npm or yarn installed. You can also run the MCP server via Docker if you prefer containerization.

Install and run using the recommended npx method. This pulls the latest MCP server package and starts it directly.

# Run directly with npx
npx -y siyuan-mcp@latest

# Or run with environment variables for SiYuan connection
SIYUAN_HOST=127.0.0.1 SIYUAN_PORT=6806 SIYUAN_TOKEN=your-token npx -y siyuan-mcp@latest

Server configuration and connection details

Configure the MCP client to connect to this server. If you prefer running the MCP client as a local process, you can use the following stdio configuration where the command and arguments are executed locally and the required environment variables supply the connection details.

{
  "mcpServers": {
    "siyuan-mcp": {
      "command": "npx",
      "args": ["-y", "siyuan-mcp@latest"],
      "env": {
        "SIYUAN_HOST": "127.0.0.1",
        "SIYUAN_PORT": "6806",
        "SIYUAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

Available tools

list_notebooks

List all notebooks and retrieve IDs and names.

create_doc

Create a new document inside a specified notebook with Markdown content.

insert_block

Insert a new content block under a given parent block with a chosen data type.

sql_query

Execute SQL queries against the underlying data store to fetch or analyze content.

export_md_content

Export document content to Markdown for backup or sharing.

upload_asset

Upload resource files and assets in bulk to the workspace.

render_template

Render dynamic content using a template system with variable substitution.

get_version

Retrieve the current version information of SiYuan Note.

check_siyuan_status

Check the availability and health of the SiYuan Note API.