CI License: AGPL v3 Python 3.13+

Trilium Notes is a hierarchical note-taking application focused on building large personal knowledge bases. Notes are organized as a tree (with support for cloning nodes into multiple locations), and the app supports rich text, code blocks, relations between notes, scripting, and a journaling system based on day/week/month/year notes.

An MCP (Model Context Protocol) server for Trilium Notes, built with FastMCP.

This project exposes Trilium's ETAPI as MCP tools, enabling LLMs and AI agents to interact with your Trilium instance.

Developed and tested against Trilium 0.102.1-test-260331-111701. Other versions may work but are not guaranteed.

# Clone the repository
git clone https://github.com/<your-username>/trilium-fastmcp.git
cd trilium-fastmcp
# Install dependencies and pre-commit hooks
make install

The server requires a Trilium ETAPI token. You can obtain one from Trilium → Options → ETAPI.

Set the following environment variables (or create a .env file):

# With Docker (recommended)
make build
make run

The MCP Inspector is available at http://localhost:6274. Use http://trilium-fastmcp:6969/mcp as the server URL inside the inspector.

By default, both update and delete tools are disabled at startup. This prevents accidental modifications to your Trilium notes. To enable them, set the following environment variables:

UPDATING_DISABLED=false # Enable update tools (update note metadata, content, etc.)
DELETING_DISABLED=false # Enable delete tools (delete notes)

Only enable these if you trust the LLM and have reviewed how the tools work.

Since Trilium's own ETAPI uses a simple token-based authentication, we chose to keep the MCP server authentication equally simple — no OAuth, no JWT infrastructure required. The server uses a static bearer token via FastMCP's StaticTokenVerifier.

When MCP_AUTH_TOKEN and MCP_CLIENT_ID are both set, the server requires an Authorization: Bearer <token> header on all requests. When unset, the server runs without authentication.

We recommend enabling authentication if your MCP server is accessible externally (i.e., not just localhost).

You can generate secure tokens with Python:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Or with OpenSSL:

openssl rand -base64 32

Then add them to your .env file:

MCP_AUTH_TOKEN=<generated-token>
MCP_CLIENT_ID=<generated-client-id>

The web clipper logic in this project was implemented using AI and was based on the ideas and behavior from zadam/trilium-web-clipper.

The clip_url tool no longer tries to persist clipped images through raw ETAPI attachment uploads. In practice, POST /etapi/attachments plus PUT /etapi/attachments/:attachmentId/content did not provide a reliable binary upload path for clipped images in Trilium, and produced either corrupted files or server-side 500 errors depending on the payload format.

Because of that, the implementation now follows Trilium's native clipper flow instead of forcing image persistence through ETAPI:

• fetch the page HTML
• extract the readable article content
• find <img> tags in the extracted HTML
• download each image with the external web client
• convert each downloaded image to a data: URL
• replace each image src with a temporary clipper image ID
• send the clip to Trilium through the native clipper endpoint
• let Trilium create the final note and image attachments internally

This matches the design of the original Trilium web clipper more closely and is what allows the final note HTML to use Trilium-native image references such as:

<img src="api/attachments/<attachmentId>/image/<filename>" />

These references are recognized by Trilium as real embedded note images, so the created attachments are not marked for automatic erasure.

This project is primarily an ETAPI-based MCP wrapper, but web clipping is the main exception.

During implementation and live validation against Trilium:

• POST /etapi/attachments with inline base64 created attachments whose content was base64 text, not image bytes
• PUT /etapi/attachments/:attachmentId/content with raw binary returned server errors or corrupted binary content
• even when the attachment record existed, the note HTML still did not use the native image reference format expected by the Trilium UI

So the final decision was:

• use the native clipper API for note creation with images
• use ETAPI only for post-processing around note placement and metadata

The native Trilium clipper saves notes according to Trilium's own clipper inbox rules. By default this is usually the day note, or another note configured in Trilium with the clipperInbox label.

This project adds a second step after the native clipper creates the note:

• if parent_note_id is provided, the server creates a branch for the clipped note under that parent
• if the note was initially created under the clipper inbox/day note, the server removes the original branch so the note ends up only under the requested parent

When no parent_note_id is provided, the server looks for a note named Web Clipper directly under root. If it does not exist, the server creates that note automatically, and then moves the clipped note there.

In other words:

• parent_note_id provided: clip natively, then move under that note
• parent_note_id omitted: clip natively, then move under root/Web Clipper

If an image cannot be downloaded or validated during clipping:

• the clip still succeeds
• a warning is returned in ClipResult.warnings
• that image keeps its original external URL in the clipped HTML

This means the note is still created even if some images cannot be internalized.

The native clipper payload carries the main clipping metadata, and this project also adds a small ETAPI post-processing step for labels:

• iconClass = "bx bx-globe"
• siteName, when available
• clipDate, using the server date

The publishedDate label, when available from the extracted page metadata, is sent in the native clipper payload so Trilium can persist it as part of the clipping flow.

Example instruction to an MCP client:

save this page https://eliassoares.com/2019/mova-se on KfLcNMe8YAMg note

That should call the clipping flow with:

• url = "https://eliassoares.com/2019/mova-se"
• parent_note_id = "KfLcNMe8YAMg"

If you omit the destination note, the clip will be saved under the Web Clipper note instead.

Add to .mcp.json (project-level) or ~/.claude/settings.json (global):

Without authentication:

{
 "mcpServers": {
 "trilium": {
 "type": "http",
 "url": "http://<your-server-ip>:6969/mcp"
 }
 }
}

With authentication (requires mcp-remote + Node.js):

{
 "mcpServers": {
 "trilium": {
 "command": "npx",
 "args": [
 "-y",
 "mcp-remote",
 "http://<your-server-ip>:6969/mcp",
 "--allow-http",
 "--header",
 "Authorization: Bearer <your-mcp-auth-token>"
 ]
 }
 }
}

Note: Claude Code currently has a known issue where it ignores Authorization headers on HTTP transport and forces OAuth discovery. Using mcp-remote as a stdio bridge is the recommended workaround.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Without authentication:

{
 "mcpServers": {
 "trilium": {
 "command": "npx",
 "args": [
 "-y",
 "mcp-remote",
 "http://<your-server-ip>:6969/mcp",
 "--allow-http"
 ]
 }
 }
}

With authentication:

{
 "mcpServers": {
 "trilium": {
 "command": "npx",
 "args": [
 "-y",
 "mcp-remote",
 "http://<your-server-ip>:6969/mcp",
 "--allow-http",
 "--header",
 "Authorization: Bearer <your-mcp-auth-token>"
 ]
 }
 }
}

Note: Both clients require mcp-remote for authenticated connections (needs Node.js). The --allow-http flag is required for non-HTTPS URLs.

make lint # Run linter
make fix # Run linter with auto-fix
make format # Run formatter
make typecheck # Run type checker (strict)
make security # Run bandit security scan
make audit # Run dependency vulnerability check
make check # Run all checks
make test # Run tests