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):

{
  "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

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

Name		Name	Last commit message	Last commit date
handlers		handlers
tests		tests
workers		workers
.dev.vars.example		.dev.vars.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
worker-configuration.d.ts		worker-configuration.d.ts

Navigation Menu

Repository files navigation

SiYuan MCP Server

Features

Architecture

Available MCP Tools

Quick Start

Option 1: CLI Mode (Local Development)

Option 2: Cloudflare Workers (Production)

Project Structure

Deploy MCP Backend (First)

Deploy CF Access Auth Worker

Deploy API Key Auth Worker

Connect with Claude Desktop

Configuration Reference

Environment Variables

CF Access Auth Worker Secrets

CLI Options

API Endpoints

OAuth Auth Worker (sy.wenri.org)

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

Development

Testing

MCP Inspector

Manual Testing

Security

Troubleshooting

Common Issues

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

SiYuan MCP Server

Features

Architecture

Available MCP Tools

Quick Start

Option 1: CLI Mode (Local Development)

Option 2: Cloudflare Workers (Production)

Project Structure

Deploy MCP Backend (First)

Deploy CF Access Auth Worker

Deploy API Key Auth Worker

Connect with Claude Desktop

Configuration Reference

Environment Variables

CF Access Auth Worker Secrets

CLI Options

API Endpoints

OAuth Auth Worker (sy.wenri.org)

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

Development

Testing

MCP Inspector

Manual Testing

Security

Troubleshooting

Common Issues

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages