Siyuan Mcp

SiYuan MCP Server

English | [繁體中文](./README.zh-TW.md)

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

| Category | Tool | Description | |------|------|------| | 🔍 Search | unified_search | Search by content/filename/tag or combined filters | | 📄 Documents | get_document_content | Read document content (paginated) | | | create_document | Create a new document | | | append_to_document | Append content | | | update_document | Replace content | | | remove_document | Remove a document | | | rename_document | Rename a document | | | move_documents | Move documents | | | get_document_tree | Get document tree by depth | | | get_human_path_by_id | Human-readable path by document ID | | | get_human_path_by_path | Human-readable path by storage path | | | get_path_by_id | Storage path by document ID | | | get_ids_by_hpath | Document IDs by human-readable path | | 📅 Daily Notes | append_to_daily_note | Append to today’s note | | 📚 Notebooks | list_notebooks | List notebooks | | | get_recently_updated_documents | Recently updated documents | | | create_notebook | Create a notebook | | | open_notebook | Open a notebook | | | close_notebook | Close a notebook | | | rename_notebook | Rename a notebook | | | remove_notebook | Remove a notebook | | | get_notebook_conf | Get notebook configuration | | | set_notebook_conf | Update notebook configuration | | 🧱 Blocks | delete_block | Delete a block | | | move_block | Move a block | | | fold_block | Fold a block | | | unfold_block | Unfold a block | | | get_child_blocks | Get child blocks | | | transfer_block_ref | Transfer block reference | | 🧱 Blocks | delete_block | Delete a block | | | move_block | Move a block | | | fold_block | Fold a block | | | unfold_block | Unfold a block | | | get_child_blocks | Get child blocks | | | transfer_block_ref | Transfer block reference | | 🧩 Attributes | get_block_attrs | Get block attributes | | | set_block_attrs | Set block attributes | | 🧮 SQL | execute_sql | Execute SQL query | | | flush_transaction | Flush SQL transaction | | 🧾 Templates | render_template | Render template by ID | | | render_sprig | Render sprig template | | 📦 Assets | upload_asset_base64 | Upload asset (base64) | | 📁 Files | get_file | Get file by path | | | put_file | Write file by path | | | remove_file | Remove file by path | | | rename_file | Rename/move file | | | list_files | List files under path | | 📤 Export | export_markdown | Export markdown | | | export_files | Export files/folders | | 🔔 Notification | push_message | Push message | | | push_error_message | Push error message | | 🖥️ System | get_boot_progress | Get boot progress | | | get_system_version | Get system version | | | get_system_time | Get system time | | 📸 Snapshots | create_snapshot | Create snapshot | | | list_snapshots | List snapshots | | | rollback_to_snapshot | Rollback snapshot | | 🏷️ Tags | list_all_tags | List all tags (prefix/depth supported) | | | batch_replace_tag | Batch replace/remove tags |

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](./LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: PurpleLiu
• Source: PurpleLiu/siyuan-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.