siyuan_mcp_server

This MCP server, Siyuan MCP Server, exposes the full Model Context Protocol API for SiYuan Note, enabling clients to interact with SiYuan notebooks, documents, and blocks through a standardized interface. It supports common MCP operations such as listing, opening, creating, renaming, moving, and deleting notebooks and documents, as well as advanced block operations, attribute management, and SQL-based queries. You can connect with MCP-enabled clients like Cursor, Claude Desktop, or other tools by configuring an MCP server entry that points to this service. The recommended quick-start method is using npx to run siyuan-mcp@latest, supplying your SiYuan host, port, and API token, and optionally a full SiYuan URL if you’re behind HTTPS reverse proxies.

To use the MCP server from clients, provide a server entry with the command and environment variables that point to your SiYuan instance. For local access, point SIYUAN_HOST to 127.0.0.1 and SIYUAN_PORT to 6806, supplying SIYUAN_TOKEN. If SiYuan is behind a reverse proxy with HTTPS, you can instead set SIYUAN_URL to the base HTTPS URL of your SiYuan instance and omit SIYUAN_HOST/PORT. The MCP server also supports Docker-based usage where you pass the same environment values to a running container. The documented operations cover notebooks, documents, blocks, attributes, and various export/import capabilities, all accessible through the MCP protocol.

Prerequisites: a machine with Node.js and npm installed, or Docker if you prefer containerized usage. You can also use the MCP client configuration in editors like Cursor or Claude Desktop.

Option A: Run with Node/NPM (recommended)

1. Install Node.js (https://nodejs.org/) and npm if not already installed.
2. Run the MCP server directly with npx (no global install required):

npx -y siyuan-mcp@latest

3. If your SiYuan instance requires authentication, export the necessary environment variables and run the command, for example:

SIYUAN_HOST=127.0.0.1 SIYUAN_PORT=6806 SIYUAN_TOKEN=your-token npx -y siyuan-mcp@latest

4. Optional: customize by embedding in an MCP config, for example using the provided mcp_config snippet.

Option B: Run with Docker

1. Pull the image:

docker pull zhizhiqq/siyuan-mcp:latest

2. Run the container with required environment variables:

docker run -d \
  -e SIYUAN_HOST=127.0.0.1 \
  -e SIYUAN_PORT=6806 \
  -e SIYUAN_TOKEN=your-token \
  --name siyuan-mcp-server \
  zhizhiqq/siyuan-mcp:latest

3. If you use a reverse proxy or HTTPS, you can still pass SIYUAN_URL instead of host/port:

docker run -d \
  -e SIYUAN_URL=https://siyuan.example.com \
  -e SIYUAN_TOKEN=your-token \
  --name siyuan-mcp-server \
  zhizhiqq/siyuan-mcp:latest

Option C: Install for client configuration (Cursor/Claude) using MCP config JSON as shown in the example.

Environment variables: SIYUAN_TOKEN is required. SIYUAN_URL overrides SIYUAN_HOST/PORT if set, enabling HTTPS reverse proxy setups. When using Docker, ensure Docker is running. The -y flag with npx auto-confirms package installation, which helps avoid interactive prompts during MCP client configuration. If you experience connection issues, verify that SiYuan is running, the token is correct, and that there are accessible notebooks. For remote setups behind a reverse proxy, prefer SIYUAN_URL for connectivity. The MCP server exposes a comprehensive set of features including Notebook, Document, Block, Attribute operations, and SQL export capabilities.