siyuan

This MCP server provides a comprehensive bridge between SiYuan Notes and AI-powered knowledge management via the Model Context Protocol (MCP). It exposes a rich set of MCP tools for notebooks, documents, blocks, assets, searches, exports, templates, SQL, and system utilities, all designed to work with SiYuan through its API token. After starting the server, you can interact with these tools through MCP clients to create and manage notebooks, documents, and blocks; perform simple and recursive searches; render templates with Sprig support; export content to Markdown and other formats; upload and manage assets (with optional OCR); run SQL queries, read and write files, and obtain system time or health checks. The AI integration offers tool recommendations, usage scenarios, performance tips, and standardized error handling, helping you automate knowledge workflows and improve response times with caching and concurrency controls.

To use it, configure your MCP client to point at the Siyuan MCP server and provide the necessary API token. The server acts as a centralized interface that translates MCP requests into SiYuan API calls and orchestrates AI-assisted operations across the feature set. Typical usage includes creating a document, performing a recursive search across notebooks, batching block operations, rendering templated content, and exporting results to Markdown or other formats for sharing or publication.

Prerequisites:

• Node.js 18+ and npm installed
• SiYuan Notes installed and configured to expose API (obtain an API token)

Install from npm globally (recommended for quick start):

# Install the MCP server globally
npm install -g siyuan-mcp-server

Or install from source:

# Clone the repository
git clone https://github.com/your-username/siyuan-mcp-server.git
cd siyuan-mcp-server

# Install dependencies and build if needed
npm install
npm run build

# Link for global usage (if building from source)
npm link

Configuration steps:

1. Start the MCP server (example using npx as the launcher):

# Ensure you have a SiYuan API token ready
# Start the MCP server via npx (no persistent install required for this example)
npx -y siyuan-mcp-server

2. If you prefer a persistent global command with environment, you can configure your MCP client as shown in the README configuration:

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["siyuan-mcp-server"],
      "env": {
        "SIYUAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

3. Ensure environment variables are set:

• SIYUAN_API_TOKEN: SiYuan API Token (required)
• SIYUAN_API_URL: Optional API URL; if omitted, the server will auto-discover available SiYuan ports (6806, 6807, 6808) or default to 6806 if discovery fails.

4. Verify the server is reachable via your MCP client and start using the available tools.

Tips and notes:

• SIYUAN_API_TOKEN is required for authentication. Keep it secure.
• If SIYUAN_API_URL is not set, the server will attempt to auto-discover the active SiYuan port. If discovery fails, you can manually specify a port like http://127.0.0.1:6806.
• The server exposes a wide range of MCP tools (Notebook, Document, Block, Asset, SQL, File, Template, Export, System) and AI integration. Use the tool names exactly as documented when calling via MCP clients.
• For performance, leverage the built-in caching, batch operations, and concurrency controls. Monitor real-time metrics if you enable performance monitoring.
• When exporting or rendering templates, ensure your templates are valid and that Sprig functions are available if you rely on Sprig features.
• If you hit authentication or connection errors, double-check token permissions and the API URL, and ensure SiYuan is running and accessible from the host running the MCP server.