思源笔记 MCP 服务器 / SiYuan MCP Server

<div align="center">

English | 中文

</div>

---

English Version

A Model Context Protocol (MCP) server for SiYuan Note, providing complete SiYuan API functionality.

🚀 Quick Start

Using npx (Recommended)

# Run directly (local SiYuan)
npx -y siyuan-mcp@latest

# Set environment variables for local access
SIYUAN_HOST=127.0.0.1 SIYUAN_PORT=6806 SIYUAN_TOKEN=your-token npx -y siyuan-mcp@latest

# For remote SiYuan behind HTTPS reverse proxy
SIYUAN_URL=https://siyuan.example.com SIYUAN_TOKEN=your-token npx -y siyuan-mcp@latest

Using Docker

# Pull image
docker pull zhizhiqq/siyuan-mcp:latest

# Run container
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

Configure MCP Client

Cursor Configuration

1. Open Cursor settings (Ctrl/Cmd + ,)
2. Search for "MCP" or "Model Context Protocol"
3. Click "Add Server" or "添加服务器"
4. Configure server information:

{
  "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"
      }
    }
  }
}

Claude Desktop Configuration

1. Open Claude Desktop settings
2. Go to "Model Context Protocol" settings
3. Add new MCP server:

{
  "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"
      }
    }
  }
}

Remote Access via HTTPS (Reverse Proxy)

If your SiYuan instance is behind a reverse proxy (e.g., Traefik, nginx) with HTTPS:

{
  "mcpServers": {
    "siyuan-mcp": {
      "command": "npx",
      "args": ["-y", "siyuan-mcp@latest"],
      "env": {
        "SIYUAN_URL": "https://siyuan.example.com",
        "SIYUAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

Docker Configuration

If you use Docker to run the service, you can configure the client to connect to the Docker container:

Cursor Docker Configuration

{
  "mcpServers": {
    "siyuan-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-e", "SIYUAN_HOST=127.0.0.1", "-e", "SIYUAN_PORT=6806", "-e", "SIYUAN_TOKEN=your-api-token-here", "zhizhiqq/siyuan-mcp:latest"],
      "env": {}
    }
  }
}

Claude Desktop Docker Configuration

{
  "mcpServers": {
    "siyuan-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-e", "SIYUAN_HOST=127.0.0.1", "-e", "SIYUAN_PORT=6806", "-e", "SIYUAN_TOKEN=your-api-token-here", "zhizhiqq/siyuan-mcp:latest"],
      "env": {}
    }
  }
}

Note: When using Docker configuration, ensure Docker is installed and running.

🔧 Environment Variables

Note: Use SIYUAN_URL when connecting to a SiYuan instance behind an HTTPS reverse proxy. When SIYUAN_URL is set, SIYUAN_HOST and SIYUAN_PORT are ignored.

📋 Common Issues

Q: What if the connection fails?

A: Please check the following steps:

1. Ensure SiYuan Note is running
2. Check if the API token is correct
3. Confirm there are open notebooks in SiYuan Note
4. Restart SiYuan Note and Cursor

Q: How to get the correct API token?

A:

1. Open SiYuan Note
2. Go to Settings → About → API Token
3. Click Generate Token or copy existing token
4. Ensure the token format is correct (usually a string of alphanumeric characters)

Q: Why use -y parameter with npx?

A: The -y parameter automatically confirms package installation without prompting for user input, which is essential for MCP client configurations where interactive prompts would cause connection failures.

Q: How to connect to SiYuan behind a reverse proxy with HTTPS?

A: Use the SIYUAN_URL environment variable instead of SIYUAN_HOST and SIYUAN_PORT:

SIYUAN_URL=https://siyuan.example.com SIYUAN_TOKEN=your-token npx -y siyuan-mcp@latest

🎯 Features

📚 Notebook Management

Notebooks are the basic organizational units of SiYuan Note, each containing multiple documents.

• list_notebooks - List all notebooks, get notebook IDs and names
• open_notebook - Open specified notebook, activate workspace
• close_notebook - Close specified notebook, release resources
• rename_notebook - Rename notebook, update display name
• create_notebook - Create new notebook, support custom names
• remove_notebook - Delete notebook, clean related data
• get_notebook_conf - Get notebook configuration information
• set_notebook_conf - Save notebook configuration, custom settings

📄 Document Management

Documents are specific content units in notebooks, supporting hierarchical structure and path management.

• create_doc - Create new document in specified notebook, support Markdown content
• rename_doc - Rename document, keep content unchanged
• rename_doc_by_id - Rename by document ID, precise operation
• remove_doc - Delete document, clean file system
• remove_doc_by_id - Delete by document ID, precise operation
• move_docs - Move documents to other locations or notebooks
• move_docs_by_id - Move by document ID, precise operation
• get_hpath_by_path - Get human-readable path by path
• get_hpath_by_id - Get human-readable path by ID
• get_path_by_id - Get storage path by ID
• get_ids_by_hpath - Get IDs by human-readable path

🧩 Block Operations

Blocks are the smallest content units in SiYuan Note, supporting flexible editing, reorganization, and referencing.

• insert_block - Insert block, support specified position and data type
• prepend_block - Insert prepend child block, add content at parent block beginning
• append_block - Insert append child block, add content at parent block end
• update_block - Update block content, support Markdown and DOM formats
• delete_block - Delete block, clean related references
• move_block - Move block to new position, support hierarchical adjustment
• get_block_kramdown - Get block kramdown source code, for export
• get_child_blocks - Get child block list, traverse block structure
• fold_block - Fold block, hide child content
• unfold_block - Unfold block, show child content
• transfer_block_ref - Transfer block reference, maintain reference relationships

🏷️ Attribute Operations

Block attributes are used to store metadata and custom information, supporting key-value pair storage.

• set_block_attrs - Set block attributes, support custom key-value pairs
• get_block_attrs - Get block attributes, read metadata information

🔍 Search and Query

Get data from SiYuan Note through SQL queries, supporting complex query conditions.

• sql_query - Execute SQL queries, support all SQLite syntax
• flush_transaction - Commit transactions, ensure data persistence

📁 File Operations

Manage files and directories in SiYuan Note workspace, support resource management.

• get_file - Get file content, read file data
• remove_file - Delete file, clean storage space
• rename_file - Rename file, update file path
• read_dir - List directory content, browse file structure
• put_file - Write file, create or update file content

📤 Export Functions

Export SiYuan Note content to various formats, support backup and sharing.

• export_md_content - Export Markdown text, maintain format
• export_resources - Export files and directories, include resource files

📢 Notification Functions

Push messages and error prompts to users, provide operation feedback.

• push_msg - Push messages, display success prompts
• push_err_msg - Push error messages, display error information

💻 System Information

Get SiYuan Note system status and runtime information, monitor system health.

• get_version - Get SiYuan Note version information
• get_current_time - Get system current time
• get_boot_progress - Get boot progress, monitor boot status
• check_siyuan_status - Check SiYuan Note status and API availability
• get_workspace_info - Get workspace and connection information

🎨 Template Functions

Use template system to create dynamic content, support variable substitution.

• render_template - Render template files, support external templates
• render_sprig - Render Sprig templates, support inline template syntax

🔄 Conversion Functions

Use Pandoc for document format conversion, support multiple output formats.

• pandoc_convert - Pandoc conversion, support multiple document formats

📎 Resource Files

Manage resource files in SiYuan Note, support batch upload.

• upload_asset - Upload resource files, support batch operations

🔧 Core Features

🚀 High Performance

• Asynchronous Processing: All API calls use asynchronous processing for faster response
• Batch Operations: Support batch document movement and block operations for improved efficiency
• Transaction Management: Built-in transaction mechanism ensures data consistency

🛡️ Secure and Reliable

• Authentication: Support API token authentication to protect data security
• Error Handling: Comprehensive error handling mechanism provides detailed error information
• **Pa

---