siyuan

This MCP server acts as a bridge between the MCP protocol and the Siyuan Notes API. Built on the official Python MCP SDK, it exposes a set of read and write tools that allow an AI Agent to query notebooks, documents, and content blocks, as well as create and update data within Siyuan. Tools are decorated with @mcp.tool() and include capabilities for finding notebooks, finding documents, searching and retrieving block content, and performing both read-only SQL queries and a full suite of write operations (create_document, update_block, delete_block, insert_block, move_block, etc.). The server also provides frontend-notification utilities (push_message and push_error_message) to relay operation results or errors back to the UI. Additionally, sensitive data in responses is auto-masked to protect credentials, tokens, passwords, and other secrets.

Prerequisites:

• Python 3.10+ (development use; uvx runtime does not require Python)
• uv (recommended) or any Python environment where you can run the server
• Siyuan Notes desktop client running and a valid API token from Siyuan settings

Installation steps:

1. Clone the repository:

git clone <repository-url>
cd siyuan-mcp-server

2. Install uv (recommended) if not using uvx:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or install via pip (alternative)
pip install uv

3. Install dependencies and verify environment (if you’re developing locally):

uv sync

4. Run or configure your MCP client to use this server (see mcp_config):

• If using uvx (recommended): ensure SIYUAN_API_TOKEN is set and start via your MCP client configuration using the provided mcpServers entry.
• If running locally: you can run the server with uv run siyuan_mcp_server from the repository root (depending on your local setup).

Configuration example for clients:

{
  "mcpServers": {
    "siyuan": {
      "command": "uvx",
      "args": ["siyuan-mcp-server"],
      "env": {
        "SIYUAN_API_TOKEN": "your_token_here"
      }
    }
  }
}

Notes and tips:

• The server relies on a Siyuan API token; keep this token secret and set it via SIYUAN_API_TOKEN in your environment.
• The uvx-based run downloads the package from PyPI at runtime, which simplifies version management and isolation.
• For local development, you can use uv run to execute the Siyuan MCP server directly from source; ensure cwd points to the project root so imports resolve correctly.
• The MCP server exposes a comprehensive set of read/write tools; understand each tool’s parameters and the ordering of operations to leverage the built-in notifications effectively.
• Be mindful of the move_block safety rules described in the repository docs to avoid misplacing blocks during moves.
• If you encounter issues with API connectivity, verify that the Siyuan API Token has the necessary permissions and that the Siyuan service is reachable from your environment.