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

| Tool Category | Tools | |---------------|-------| | Document Read | List notebooks, get document tree, read document content, outline | | Document Write | Create, rename, move, delete documents | | Block Operations | Insert, update, delete, move blocks (with batch support) | | Search | Full-text search (siyuan_find_block), SQL queries | | Vector Search | RAG-based semantic search (requires RAG backend) | | Daily Notes | Create and manage daily notes | | Flashcards | Create and review flashcards | | Attributes | Manage custom attributes on documents/blocks | | Relations | Manage block relations | | Assets | Upload assets (batch, URL fetch, JSON auto-serialize) | | File System | Read/write files, create archives | | Templates | Render and manage SiYuan templates | | Help Docs | Built-in documentation resources | | Utilities | Get time, push notifications, reindex, flush transactions |

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): ``json { "mcpServers": { "siyuan-oauth": { "command": "npx", "args": ["mcp-remote", "https://sy.wenri.org/sse"] } } } ``

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

Configuration Reference

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SIYUAN_KERNEL_URL | Yes | SiYuan kernel URL | | SIYUAN_KERNEL_TOKEN | If auth enabled | SiYuan API token | | COOKIE_ENCRYPTION_KEY | Workers mode | For download URL encryption | | RAG_BASE_URL | Optional | RAG backend URL for vector search | | RAG_API_KEY | Optional | RAG backend API key | | FILTER_NOTEBOOKS | Optional | Newline-separated notebook IDs to include | | FILTER_DOCUMENTS | Optional | Newline-separated document IDs to include | | READ_ONLY_MODE | Optional | allow_all, allow_non_destructive, or deny_all | | AUTO_APPROVE_LOCAL_CHANGE | Optional | Auto-approve local change operations |

CF Access Auth Worker Secrets

| Secret | Description | |--------|-------------| | ACCESS_CLIENT_ID | From CF Access SaaS app dashboard | | ACCESS_CLIENT_SECRET | From CF Access SaaS app dashboard | | ACCESS_TOKEN_URL | Token endpoint URL | | ACCESS_AUTHORIZATION_URL | Authorization endpoint URL | | ACCESS_JWKS_URL | JWKS endpoint URL |

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

SiYuan MCP Server