Which integrations are available for this server?

Provides comprehensive tools for interacting with a SiYuan Note knowledge base, including reading, writing, searching, and managing documents, blocks, flashcards, attributes, relations, assets, templates, and more.

How do I use SiYuan MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SiYuan MCP Server search my notes for meeting notes from last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

SiYuan MCP Server

by Wenri

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

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

Related MCP server: SiYuan MCP Server

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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Wenri/siyuan-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server