SiYuan

You can run a complete MCP server for SiYuan Note that lets AI assistants like Claude or Cursor interact with your notes. This server implements the Model Context Protocol, enabling powerful, natural-language access to notebooks, documents, daily notes, and more while keeping actions organized through standard MCP tooling.

How to use

Install and run the MCP server, then connect your MCP client to it. With the server active, you can ask your AI assistant to search across content, read or create documents, manage notebooks and daily notes, handle tags, and create or restore snapshots. Use straightforward prompts like listing notebooks, searching for documents, creating or moving notes, and appending to the daily note. The MCP server exposes a set of practical tools that translate your natural-language requests into SiYuan operations.

How to install

Follow these concrete steps to prepare and run the MCP server so your AI assistant can work with SiYuan notes.

Configuration and usage notes

Prerequisites you need to satisfy before starting the MCP server:

# Clone the project
# (Use the exact repository name shown in your source tree)
# Then install dependencies and build as described in the configuration steps

Obtain your SiYuan API Token from SiYuan Note under Settings → About → API Token. This token is used to authorize MCP operations.

Ensure SiYuan is running locally. The default base URL is http://127.0.0.1:6806. If you run SiYuan on a different port, adjust the baseUrl accordingly in the configuration.

Configure the MCP client to connect to the Siyuan MCP server. Create or edit the MCP configuration file for Cursor or Claude Desktop as shown below. The configuration uses an MCP stdio transport that launches the MCP server via npx with your token and baseUrl.

{
  "mcpServers": {
    "siyuan-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@porkll/siyuan-mcp",
        "stdio",
        "--token",
        "YOUR_API_TOKEN_HERE",
        "--baseUrl",
        "http://127.0.0.1:6806"
      ]
    }
  }
}

If you installed globally, you can substitute the command with "command": "siyuan-mcp" in place of "npx".

For Claude Desktop or Cursor, place a matching configuration in the platform’s MCP section. The same JSON snippet above applies; adjust it if your client requires a slightly different placement or file path.

After configuring, restart your MCP client to apply changes. Then test with simple requests such as listing notebooks, searching documents, creating new notes, or showing recently modified documents.

Additional notes on usage and troubleshooting

If you encounter issues, verify the following common causes: SiYuan is running on the expected URL, the API token is correct, and you have restarted the MCP client after applying changes. Check logs in your MCP client for error messages.

You can adapt the setup to remote SiYuan instances by changing the baseUrl parameter in the configuration to the remote address, such as http://your-server.com:6806. Ensure your network allows access to the specified port.

Progressive usage patterns and examples

Once connected, you can perform common operations via natural language prompts, such as listing notebooks, searching by keywords, creating documents in a specific notebook, moving documents under a parent, or appending to today’s daily note. You can also create and manage snapshots to safeguard your data before large changes.

Notes on security and safety

Treat your API token as a secret and do not expose it in shared environments. Regularly rotate credentials and limit access to trusted clients. Validate all actions in a test environment before applying changes to your production SiYuan data.

Available tools

unified_search

Unified search across content, filename, tag, and combinations.

get_document_content

Retrieve the markdown content of a document.

create_document

Create a new document in a specified notebook.

append_to_document

Append content to an existing document.

update_document

Overwrite content of a document.

move_documents

Move one or more documents to a new location within notebooks.

get_document_tree

Fetch the document tree structure with a specified depth.

append_to_daily_note

Append content to today’s daily note, auto-creating if needed.

list_notebooks

List all notebooks in the workspace.

get_recently_updated_documents

Retrieve documents recently modified.

create_snapshot

Create a data snapshot for backup.

list_snapshots

List available snapshots.

rollback_to_snapshot

Rollback to a selected snapshot.

list_all_tags

List all unique tags in the workspace with optional filtering by prefix and depth.

batch_replace_tag

Batch replace or remove tags across all documents.