An MCP server for siyuan-note

中文

A plugin that provides MCP service for Siyuan Note.

🌻 Features

• Most tools support the exclude document function.

• It includes certain input parameter validation and is not a direct API wrapper for SiYuan Note.

• Ready to use once the plugin is installed and enabled on the desktop client; Docker and mobile platforms are not supported.

Related MCP server: MCP Apple Notes

✨ Quick Start

• Download from the marketplace or 1. unzip the package.zip in Release, 2. move the folder to workspace/data/plugins/, 3. and rename the folder to syplugin-anMCPServer;

• Enable the plugin;

• The plugin listens on port 16806 by default (Host: 127.0.0.1), please use http://127.0.0.1:16806/sse as the server access address;

⭐ If this is helpful to you, please consider giving it a star!

🛠 Supported Tools (Summary)

For detailed tools, supported excluded documents, and other notes, please refer to the Supported Tools section.

• Document and block operations: create, read, update, and delete;

• Database operations:

  • Create databases, add/delete/update database rows, add/delete database columns, and retrieve database structure information;

• Attribute operations: create, read, update, and delete;

• Flashcard operations: create flashcards from Markdown content, create flashcards by block ID, delete flashcards by block ID;

• Template operations: retrieve existing templates, get raw template file content, preview template rendering results, preview Sprig rendering results, create or overwrite templates, render templates and insert at the beginning of a document, delete existing templates;

• Notebook operations: list notebooks, rename notebooks;

❓ Frequently Asked Questions

• Q1: How to use it in an MCP client? Please refer to the subsequent sections.

• Q2: What are some common MCP clients?

  • Please refer to: https://github.com/punkpeye/awesome-mcp-clients or https://modelcontextprotocol.io/clients.

• Q3: Does the plugin support authentication?

  • Version v0.2.0 and above support authentication. After setting an authentication token in the plugin settings, you must set the authorization request header in your MCP client with the value Bearer YourToken.

• Q4: Can it be used in Docker?

  • No. The plugin depends on a Node.js environment and does not support running on mobile devices or within Docker.

    To support SiYuan deployed in Docker, it is recommended to switch to other MCP projects. Some projects are listed here.

    Alternatively, you can modify the code to decouple this plugin from the SiYuan frontend.

• Q5: How can I view the configured authorization code?

  • Authorization codes are saved as hashes. You can only modify them; you cannot view the currently active authorization code.

• Q6: When connecting an MCP client, I get an error Invalid Host: x.x.x.x or something similar. How do I fix it?

  {
    "jsonrpc": "2.0",
    "error": {
      "code": -32000,
      "message": "Invalid Host: x.x.x.x"
    },
    "id": null
  }

  • By default, for security reasons, the service only handles requests from localhost. If you need to access it via a specific domain or connect to the MCP service in a non-local environment, you must manually declare it in Plugin Settings - Allowed Hosts.

  • Fill in this setting with the corresponding local network IP of the computer or the bound domain name.

  • Simply put: whatever IP or domain name you entered in the MCP client must also be entered here.

• Q7: I only connected once, why does the settings page show a connection count greater than 1?

  • Delayed Statistics: Please click the refresh status button manually to get the latest results.

  • Connection Leak: Some MCP clients do not send a standard disconnect signal when closing, causing old connections to remain occupied in the background. When the function is restarted, the system establishes a new overlapping connection.

  • Multi-device Connection: Please confirm if other software is accessing the MCP service or the relevant port.

  • Still having issues? Please check the plugin logs or set an authorization code to prevent information leakage.

• Q8: What is the "Vector Index Client Plugin - Query" tool?

  • This tool retrieves matching content blocks or answers questions directly via Knowledge Graph/Vector Search.

  • To use this tool, you need to download, enable, and correctly configure the syplugin-vectorIndexClient plugin.

  • Currently, this plugin only supports lightRAG-server.

• Q9: How to better utilize the MCP services provided by the plugin?

  • Limit available tools for different tasks. For example, disable template-related tools when you don't need to manipulate templates.

  • The plugin provides Prompts suitable for certain task types. You need to use these related prompts in your MCP client; please refer to each client's documentation for specific operation methods.

• Q10: Can I create an HTTPS-based service?

  • Yes. You need to place two files, server-key.pem and server-cert.pem, in the directory Workspace/data/storage/petal/syplugin-anMCPServer, then restart SiYuan Note. If the notification message when the MCP service starts ends with with HTTPS, it means it has been enabled.

  • Q10.1: MCP client shows net::ERR_CERT_AUTHORITY_INVALID

    • This is expected with self-signed certificates. Refer to the previous point: a) Delete the two certificate files and continue using HTTP; b) Replace them with certificates issued by an authoritative CA; c) Or add the self-signed certificate to your trust list (not recommended).

  • Q10.2: MCP client shows net::ERR_EMPTY_RESPONSE

    • Please check: if HTTPS is used, the client URL must start with https://. Otherwise, delete the two certificate files and continue using HTTP.

  • Q10.3: MCP client shows net::ERR_CERT_COMMON_NAME_INVALID

    • When generating the certificate, ensure the correctness of the CN (Common Name) field and add the subjectAltName (SAN) field. Using localhost as an example:

      openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes -keyout server-key.pem -out server-cert.pem -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

How to Configure in an MCP Client?

Different MCP clients require different configuration methods. Please refer to the MCP client documentation.

MCP clients are continuously updated, so the configuration or usage instructions here may not be directly applicable and are for reference only.

Here, we assume: the plugin’s port is 16806, and the authorization token is abcdefg.

Modify the MCP application’s configuration, select the Streamable HTTP type, and configure the endpoint.

Clients Supporting Streamable HTTP

The following configuration uses Cherry Studio as an example. Different MCP clients may require different configuration formats—please refer to the MCP client documentation.

Plugin Without Authorization Token

1. Type: Select Streamable HTTP (streamablehttp);

2. URL: http://127.0.0.1:16806/mcp;

3. Headers: Leave empty;

Plugin With Authorization Token

1. Type: Select Streamable HTTP (streamablehttp);

2. URL: http://127.0.0.1:16806/mcp;

3. Headers: Authorization=Bearer abcedfg;

Clients Supporting Only Stdio

If the MCP client does not support HTTP-based communication and only supports stdio, a conversion method is needed.

Here, we use node.js + mcp-remote@next.

1. Download Node.js: https://nodejs.org/en/download

2. Install mcp-remote@next:

npm install -g mcp-remote@next  

The following configuration uses 5ire as an example. Different MCP clients may require different configuration formats—please refer to the MCP client documentation.

Plugin Without Authorization Token

Command:

npx mcp-remote@next http://127.0.0.1:16806/mcp  

Plugin With Authorization Token

Command:

npx mcp-remote@next http://127.0.0.1:16806/mcp --header Authorization:${AUTH_HEADER}  

Environment Variable:

Name: AUTH_HEADER
Value: Bearer abcdefg

🔧 Supported Tools

🙏 References & Acknowledgements

Some dependencies are listed in package.json.