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

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

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | SIYUAN_URL | Full URL for SiYuan (e.g., https://siyuan.example.com). If set, overrides HOST/PORT. | - | No | | SIYUAN_HOST | SiYuan server address | 127.0.0.1 | No | | SIYUAN_PORT | SiYuan server port | 6806 | No | | SIYUAN_TOKEN | API token | - | Yes |

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

... View full README on GitHub