# An MCP server for siyuan-note
[δΈζ](./README_zh_CN.md)
> A plugin that provides MCP service for [Siyuan Note](https://github.com/siyuan-note/siyuan).
## π» 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**.
## β¨ 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](#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](https://github.com/punkpeye/awesome-mcp-clients) or [https://modelcontextprotocol.io/clients](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](https://github.com/siyuan-note/siyuan/issues/13795).
>
> 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?**
```json
{
"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](https://github.com/OpaqueGlass/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](https://github.com/CherryHQ/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`:
```bash
npm install -g mcp-remote@next
```
The following configuration uses [5ire](https://5ire.app/) 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
> [!WARNING]
>
> Not all tools enforce strict excluded document validation. Before using excluded documents or after updating MCP tools, please read the tool support list carefully and consider disabling some tools.
| Target | R/W | Destructive / Manual review available
| Tool Function | Excluded Doc | Status / Notes |
|:--- |:--- |:--- |:--- |:---: |:--- |
| **Documents & Blocks** | | | | | |
| | Read | | Search using SQL | β οΈ | Excluded documents are only checked if the result contains IDs and the number of returned items < 300 |
| | | | Get document Markdown by ID | β
| β |
| | | | Get block Kramdown by ID | β
| β |
| | | | List child documents of a document | β
| β |
| | | | List child blocks | β
| β |
| | | | Vector Retrieval Client Plugin - Query | β | Requires downloading and properly configuring the syplugin-vectorIndexClient plugin
Excluded documents are not yet supported for this tool |
| | | | Get backlinks by ID | β
| β |
| | Write | | Append content to daily note | β
| β |
| | | | Append content to specified document by ID | β
| domstring not supported |
| | | | Create new document at specified position by ID | β
| domstring not supported |
| | | | Insert child block (before / after) | β
| domstring not supported |
| | | | Insert block at specified position | β
| domstring not supported |
| | | Yes / Yes | Update block | β
| domstring not supported |
| | | | Rename document | β
| β |
| | | Yes / No | Move document | β
| β |
| | | Yes / No | Move block | β
| β οΈ Moving headings requires folding first, which will cause folding state to be lost |
| | | Yes / Yes | Delete document | β
| β |
| | | Yes / Yes | Delete block | β
| β |
| **Database** | | | | | Only basic database operations are supported, see [reference](./static/data_db_EN.md) |
| | Read | | Get database schema | β
| β |
| | | | Get database view schema | β
| β |
| | | | Query database results | β
| β |
| | | | Get block ID where database is located | β
| β |
| | | | Search Existing Databases| β
| β |
| | Write | | Create database | β
| β |
| | | | Add new database row | β
| β |
| | | | Modify database row | β
| Rollup, template and relation column types are not supported |
| | | Yes / Yes | Delete database row | β
| β |
| | | | Add database column | β
| β |
| | | Yes / Yes | Delete database column | β
| β |
| **Attributes** | | | | | |
| | Read | | Read attributes | β
| β |
| | Write | | Modify attributes (add / delete / update) | β
| β |
| **Flashcards** | | | | | |
| | Write | | Create flashcard from Markdown content | β
| β |
| | | | Create flashcard by block ID | β
| β |
| | | Yes / No | Delete flashcard by block ID | β | β |
| **Templates** | | | | | |
| | Read | | List existing templates | β | β |
| | | | Raw template file content | β | β |
| | | | Preview template rendering result | β οΈ | Only kramdown is returned; checks may be bypassed via getBlock |
| | | | Preview Sprig rendering result | β | Does not involve user documents |
| | Write | | Create or overwrite template | β | Does not involve user documents |
| | | | Render template and insert at document start | β οΈ | Insertion is fixed at document start and cannot be specified
Since functions like `getBlock` can be used in templates, this tool may bypass checks to access excluded documents |
| | | | Delete existing template | β | β |
| **Notebooks** | | | | | |
| | Read | | List notebooks | β | Does not involve user documents |
| | Write | | Rename notebook | β
| β |
## π References & Acknowledgements
> Some dependencies are listed in `package.json`.
| Developer/Project | Project Description | Citation |
|---------------------------------------------------------------------|----------------|--------------|
| [thuanpham582002/tabby-mcp-server](https://github.com/thuanpham582002/tabby-mcp-server) | Provides MCP service within the terminal software Tabby; MIT License | Implementation method of MCP service |
| [wilsons](https://ld246.com/article/1756172573626/comment/1756384424179?r=wilsons#comments) / [Frostime](https://ld246.com/article/1739546865001#%E6%80%9D%E6%BA%90-SQL-%E6%9F%A5%E8%AF%A2-System-Prompt) | System Prompt CC BY-SA 4.0 | System Prompts etc. which locate at `static/` |