SiYuan MCP Server

A Model Context Protocol (MCP) server for SiYuan Note with pluggable authentication. Enables AI assistants like Claude to interact with your SiYuan knowledge base through a secure, authenticated API.

Features

• Full SiYuan Integration: Read, write, search, and manage documents, blocks, flashcards, and more
• Pluggable Authentication:
• OAuth 2.1 + PKCE via Cloudflare Access (supports Okta, Azure AD, Google, etc.)
• Simple API key authentication via X-SiYuan-Key header
• Multi-Worker Architecture: Separate auth and MCP backend for flexibility
• Two Deployment Modes:
• Cloudflare Workers: Production deployment with multiple auth options
• CLI (stdio): Standalone MCP server for direct Claude Desktop integration
• RAG Support: Optional vector search integration for semantic document retrieval
• Read-Only Mode: Configurable restrictions for safe read-only access

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        Cloudflare Workers Mode                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────┐     ┌─────────────────────────────┐   │
│  │ CF Access Auth (sy.wenri.org)│     │ API Key Auth (api-sy.wenri.org)│
│  │ - OAuth flow (/authorize)   │     │ - X-SiYuan-Key validation   │   │
│  │ - /download (grant-based)   │     │ - /download (stateless)     │   │
│  └──────────────┬──────────────┘     └──────────────┬──────────────┘   │
│                 │ Service Binding                   │ Service Binding  │
│                 └───────────────────┬───────────────┘                  │
│                                     ▼                                  │
│                     ┌───────────────────────────────┐                  │
│                     │      MCP Backend Worker       │                  │
│                     │   - SiyuanMCP Durable Object  │                  │
│                     │   - Tool execution            │                  │
│                     │   - SiYuan Kernel API calls   │                  │
│                     └───────────────────────────────┘                  │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                            CLI Mode (stdio)                             │
├─────────────────────────────────────────────────────────────────────────┤
│  Claude Desktop ←──stdio──→ handlers/cli.ts ←──HTTP──→ SiYuan Kernel   │
└─────────────────────────────────────────────────────────────────────────┘

Available MCP Tools

Quick Start

Option 1: CLI Mode (Local Development)

Use stdio transport for direct Claude Desktop integration:

# Clone and install
git clone <repo-url>
cd mcp_saas
npm install

# Run with SiYuan kernel URL
npx tsx handlers/cli.ts --kernel-url http://localhost:6806

# Or with authentication token
npx tsx handlers/cli.ts --kernel-url http://localhost:6806 --token YOUR_TOKEN

Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["tsx", "/path/to/handlers/cli.ts", "--kernel-url", "http://localhost:6806"]
    }
  }
}

Option 2: Cloudflare Workers (Production)

Deploy multi-worker MCP server to Cloudflare Workers.

#### Project Structure

workers/
├── mcp-backend/           # MCP Backend (internal, no public routes)
│   ├── index.ts          # Entry point, WorkerEntrypoint with RPC methods
│   ├── server/           # MCP server core
│   │   ├── agent.ts      # SiyuanMCP Durable Object
│   │   └── index.ts      # Server initialization
│   └── wrangler.jsonc    # DO bindings
│
├── auth-cfaccess/         # CF Access OAuth (sy.wenri.org)
│   ├── index.ts          # OAuthProvider + RPC forwarding
│   ├── access-handler.tsx # Hono app: OAuth flow, consent (JSX)
│   └── wrangler.jsonc    # KV + service binding
│
└── auth-apikey/           # API Key Auth (api-sy.wenri.org)
    ├── index.ts          # Hono app: X-SiYuan-Key validation
    └── wrangler.jsonc    # Service binding

#### Deploy MCP Backend (First)

cd workers/mcp-backend
wrangler secret put SIYUAN_KERNEL_TOKEN
# If SiYuan kernel is behind CF Access:
wrangler secret put CF_ACCESS_SERVICE_CLIENT_ID
wrangler secret put CF_ACCESS_SERVICE_CLIENT_SECRET
npx wrangler deploy

#### Deploy CF Access Auth Worker

cd workers/auth-cfaccess

# Create KV namespace (one-time)
npx wrangler kv namespace create "OAUTH_KV"
# Update KV ID in wrangler.jsonc

# Set secrets from CF Access SaaS app dashboard
wrangler secret put ACCESS_CLIENT_ID
wrangler secret put ACCESS_CLIENT_SECRET
wrangler secret put ACCESS_TOKEN_URL
wrangler secret put ACCESS_AUTHORIZATION_URL
wrangler secret put ACCESS_JWKS_URL
wrangler secret put COOKIE_ENCRYPTION_KEY  # openssl rand -hex 32

npx wrangler deploy

#### Deploy API Key Auth Worker

cd workers/auth-apikey
wrangler secret put SIYUAN_KERNEL_TOKEN
wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler deploy

#### Connect with Claude Desktop

Via OAuth (CF Access):

{
  "mcpServers": {
    "siyuan-oauth": {
      "command": "npx",
      "args": ["mcp-remote", "https://sy.wenri.org/sse"]
    }
  }
}

Via API Key:

claude mcp add siyuan https://api-sy.wenri.org/sse \
  -t sse -H "X-SiYuan-Key: YOUR_TOKEN"

Configuration Reference

Environment Variables

CF Access Auth Worker Secrets

CLI Options

Options:
  -u, --kernel-url <url>     SiYuan kernel URL (required)
  -t, --token <token>        SiYuan API token
  --rag-url <url>            RAG backend URL
  --rag-key <key>            RAG API key
  --filter-notebooks <ids>   Notebook IDs to filter (newline-separated)
  --filter-documents <ids>   Document IDs to filter (newline-separated)
  --read-only <mode>         Read-only mode: allow_all, allow_non_destructive, deny_all
  -h, --help                 Show help message

API Endpoints

OAuth Auth Worker (sy.wenri.org)

• GET /authorize - Initiate OAuth flow
• GET /callback - OAuth callback, consent page
• POST /callback - Complete authorization
• POST /token - Token endpoint
• POST /register - Dynamic client registration
• GET /.well-known/oauth-authorization-server - OAuth metadata
• POST /mcp, GET /sse - MCP endpoints (forwarded to backend via RPC)
• GET /download/* - File downloads (grant-based validation)

API Key Auth Worker (api-sy.wenri.org)

• POST /mcp, GET /sse - MCP endpoints (X-SiYuan-Key required, forwarded via RPC)
• GET /download/* - File downloads (stateless validation)

Development

# Install dependencies
npm install

# Local development - start each worker separately
cd workers/mcp-backend && npx wrangler dev    # http://localhost:8787
cd workers/auth-cfaccess && npx wrangler dev  # http://localhost:8788
cd workers/auth-apikey && npx wrangler dev    # http://localhost:8789

# Run tests
npm test

# Deploy (order matters: backend first)
cd workers/mcp-backend && npx wrangler deploy
cd workers/auth-cfaccess && npx wrangler deploy
cd workers/auth-apikey && npx wrangler deploy

Testing

MCP Inspector

npx @modelcontextprotocol/inspector@latest
# Connect to deployed URL or localhost

Manual Testing

# Test OAuth discovery
curl https://sy.wenri.org/.well-known/oauth-authorization-server

# Test API key auth
curl -X POST https://api-sy.wenri.org/mcp \
  -H "X-SiYuan-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Security

• OAuth 2.1 + PKCE: Prevents authorization code interception
• Cloudflare Access: Enterprise identity provider support
• Service Bindings: Internal worker communication (no public routes for backend)
• Durable Objects: Session state with SQLite storage
• Download URL Encryption: Time-bound, path-bound download tokens
• Read-Only Mode: Optional restriction of write operations

Troubleshooting

Common Issues

"SIYUAN_KERNEL_URL not configured"

• Set SIYUAN_KERNEL_URL in wrangler.jsonc vars

"Failed to get SiYuan config"

• Verify SiYuan kernel is running and accessible
• Check SIYUAN_KERNEL_TOKEN if authentication is enabled

"Unauthorized: Missing auth context"

• MCP backend requires auth headers from auth workers
• Cannot be accessed directly; use auth worker endpoints

"Invalid or expired state"

• OAuth state expired (10 min timeout)
• Verify KV namespace is configured correctly

Tool not appearing

• Check READ_ONLY_MODE setting
• Verify tool annotations allow current mode

License

MIT