SiYuan

You run a Model Context Protocol (MCP) server that integrates SiYuan notes with AI capabilities and smart knowledge management. This guide shows you how to use the server with an MCP client, how to install it, and how to configure everything for practical, productive workflows.

How to use

Connect your MCP client to the SiYuan MCP Server to access notebooks, documents, blocks, templates, exports, assets, SQL queries, and system tools. Use the unified tool interface to perform actions such as creating documents, searching across notebooks, rendering templates, exporting content, uploading assets, and running AI-assisted workflows. The server exposes a comprehensive set of tools that you can call from your MCP client to manage data, render content, and process information.

Practical usage patterns include: creating documents in a notebook, reading and updating blocks, performing recursive searches across multiple notebooks, rendering templates with dynamic content, exporting documents to Markdown or other formats, and leveraging AI-driven recommendations for tool selection and workflow optimization.

How to install

Prerequisites: you need Node.js 18+ installed on your system.

Install the MCP server globally using npm.

From source, clone the MCP server repository, install dependencies, build, and link for use.

# Install MCP server globally
npm install -g siyuan-mcp-server

# From source (example flow)
git clone https://github.com/your-username/siyuan-mcp-server.git
cd siyuan-mcp-server
npm install
npm run build
npm link

Configuration and startup notes

The server is configured to run as an MCP stdio endpoint using a local command that launches the MCP server process. You provide an environment variable for the SiYuan API token, and you can optionally specify the API URL to connect to a specific port.

Key environment variables you will use are shown in the example configuration.

Configuration example for the MCP client

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["siyuan-mcp-server"],
      "env": {
        "SIYUAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

Environment and port discovery notes

The SIYUAN_API_URL is optional. If you do not configure it, the system will automatically discover the available port used by SiYuan. If you want to force a specific port, you can set the SIYUAN_API_URL environment variable.

The system scans common ports (6806, 6807, 6808) to connect to SiYuan. If automatic discovery fails, it will attempt the default port 6806.

Security considerations

Protect your API token and limit access to the MCP server. Use secure channels for communication between the MCP client and server, and rotate tokens periodically.

Examples of common workflows

Create a new document in a notebook, then export it to Markdown for sharing.

Search across notebooks for a keyword, then render a templated summary based on the results.

Upload an asset (image) to a document and run OCR to extract text from the image.

Notes on updates and troubleshooting

If you encounter connection issues, verify that SiYuan is running and that the API token is valid. Ensure the SIYUAN_API_URL, if set, points to the correct address. Check that the MCP server process is running and that the MCP client is configured to target the correct server.

Additional capabilities you can leverage

The server includes notebook, document, block, search, template, export, assets, SQL, file, and system tool capabilities. You can perform operations such as listing notebooks, creating and updating documents, reading and writing blocks, performing simple and recursive searches, rendering templates with Sprig functions, exporting to Markdown or other formats, handling assets with OCR, querying SQL, and obtaining the current time in various formats.

Available tools

list_notebooks

List all notebooks available in SiYuan.

open_notebook

Open a specified notebook to work with its contents.

close_notebook

Close an open notebook session.

rename_notebook

Rename a notebook.

remove_notebook

Delete a notebook.

create_document

Create a new document in a notebook with a given path, title, and content.

get_document

Retrieve the content of a specific document.

update_document

Update the content or metadata of a document.

delete_document

Delete a document.

list_documents

List documents within a notebook or folder.

batch_read_all

Batch read multiple documents efficiently.

create_block

Create a new block within a document.

get_block

Retrieve a block’s content and attributes.

update_block

Update an existing block.

delete_block

Delete a block.

prepend_block

Insert a block before a target block.

append_block

Append a block after a target block.

fold_block

Fold a block to collapse its content.

unfold_block

Unfold a folded block.

transfer_block_ref

Move block references between blocks.

set_block_attrs

Set attributes on a block.

get_block_attrs

Get attributes from a block.

batch_create_blocks

Batch create multiple blocks.

batch_update_blocks

Batch update multiple blocks.

batch_delete_blocks

Batch delete multiple blocks.

simple_search

Perform a simple keyword search across notes.

recursive_search

Perform a deep, recursive search across content.

search_in_document

Search within a specific document.

render_template

Render a template with data to generate formatted content.

render_sprig_template

Render a Sprig-based template for advanced formatting.

export_markdown

Export a document or data set to Markdown format.

export_file

Export content to a specified format (PDF, Word, HTML, etc.).

export_expand

Export a tree-structured representation that preserves document hierarchy.

upload_asset

Upload an asset (image, file) to a document.

list_assets

List all assets within a document.

rename_asset

Rename an asset file.

ocr_asset

Run OCR on an asset to extract text.

query_sql

Execute SQL queries to retrieve data.

read_file

Read a file from the filesystem.

write_file

Write content to a file.

delete_file

Delete a file from the filesystem.

list_files

List files in a directory.

get_current_time

Get the current real-world time in various formats.