Siyuan

English | 繁體中文

A SiYuan MCP server maintained by PurpleLiu. It connects AI tools to SiYuan Note through the Model Context Protocol (MCP) for safe search, reading, creation, and organization of your notes.

Compatible with Claude Desktop, Cursor, OpenClaw, and any MCP-compatible client.

Features

• 66 tools covering search, documents, blocks, notebooks, daily notes, snapshots, and tags
• Unified search — content, filename, tag, or combined filters
• Document tree — browse notebook hierarchy by depth
• Daily notes — auto-create today’s note if it doesn’t exist
• Snapshot management — create/list/rollback
• Stdio & HTTP transports
• TypeScript full type definitions

Quick Start

Install

git clone https://github.com/PurpleLiu/siyuan-mcp.git
cd siyuan-mcp
npm install && npm run build
npm install -g .

Get Your SiYuan API Token

SiYuan → Settings → About → API Token

Environment Variables (optional)

export SIYUAN_TOKEN=your-token
export SIYUAN_BASE_URL=http://127.0.0.1:6806
export SIYUAN_VERBOSE=1   # optional

Configure Your MCP Client

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "siyuan": {
      "command": "siyuan-mcp",
      "args": ["stdio", "--token", "YOUR_TOKEN", "--baseUrl", "http://127.0.0.1:6806"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "siyuan": {
      "command": "siyuan-mcp",
      "args": ["stdio", "--token", "YOUR_TOKEN", "--baseUrl", "http://127.0.0.1:6806"]
    }
  }
}

Config locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Tools

Usage Examples

"List all notebooks"
"Search notes about kubernetes"
"Show the Work notebook tree with 3 levels"
"Create a meeting note under Projects/2026"
"Append today’s standup notes to my daily note"
"Move these three documents into Archive"
"What tags do I have under 'project/'?"
"Get block attributes for this note"
"Set a custom attribute on a block"
"Run an SQL query to find recently updated notes"
"Render a template with variables"
"Upload an image asset"
"Export this document to markdown"
"List files under /data"
"Push a notification message"
"Check SiYuan system version"

Using as a Library

import { createSiyuanTools } from '@purpleliu/siyuan-mcp';

const siyuan = createSiyuanTools('http://127.0.0.1:6806', 'your-token');

const notebooks = await siyuan.listNotebooks();
const content = await siyuan.getFileContent(documentId);
const results = await siyuan.search.query(
  "SELECT * FROM blocks WHERE content LIKE '%keyword%'"
);

Development

npm install          # Install dependencies
npm run build        # Build
npm run watch        # Watch mode
npm run lint         # Lint
npm run format       # Format

# Manual testing
npm run mcp:stdio -- --token YOUR_TOKEN --baseUrl http://127.0.0.1:6806
npm run mcp:http -- --token YOUR_TOKEN --port 3000 --baseUrl http://127.0.0.1:6806

Project Structure

├── src/               # Core library
│   ├── api/           # SiYuan API client
│   ├── types/         # TypeScript types
│   └── utils/         # Helpers
├── mcp-server/        # MCP server
│   ├── bin/           # CLI entry (stdio/http)
│   ├── core/          # Server core & registry
│   └── handlers/      # Tool handlers
└── dist/              # Build output

License

Apache-2.0