trilium-mcp

MCP server for TriliumNext Notes — full ETAPI access with infrastructure ontology tools

A Model Context Protocol (MCP) server that exposes TriliumNext Notes via ETAPI to AI assistants like Claude Code. Built in Java 21 using the official MCP Java SDK.

Features

38 tools across 7 categories:

Notes

Search

Attributes

Navigation

Branches

System

Infrastructure Ontology

Requirements

• Java 21+
• Maven 3.6+
• A running TriliumNext Notes instance with ETAPI enabled

Quick Start

1. Build

git clone https://github.com/wrxck/trilium-mcp.git
cd trilium-mcp
mvn clean package -q

This produces a single uber-jar at target/trilium-mcp-1.0.0.jar.

2. Init

java -jar target/trilium-mcp-1.0.0.jar --init

The init wizard:

1. Prompts for your Trilium URL (default http://127.0.0.1:8080) and ETAPI token
2. Validates the connection against /etapi/app-info
3. Saves credentials to ~/.trilium-mcp/config.properties with 600 permissions
4. Registers the server with Claude Code via claude mcp add

Generate an ETAPI token in Trilium: Options → ETAPI → Generate new token

The init is idempotent — safe to re-run. If config already exists it skips to registration. If already registered it skips that too.

If Claude Code isn't on your PATH:

java -jar target/trilium-mcp-1.0.0.jar --init --claude-binary ~/.local/bin/claude

3. Verify

Restart Claude Code. Ask: "What version of Trilium am I running?" — the app_info tool will respond with your instance details.

If auto-registration failed, register manually:

claude mcp add --scope user --transport stdio trilium -- \
  java -jar /path/to/trilium-mcp-1.0.0.jar

Tool Reference

Notes

Search

Attributes

Navigation

Branches

System

Infrastructure Ontology

Ontology Schema

The ontology tools operate on a convention of Trilium labels and relations. Notes are given an #entityType label to classify them:

Project labels

Relations

Folder structure

The write tools expect these folders to exist at the top level of your note tree:

Deployments/
Incidents/
Runbooks/

The tools search for these by title using note.title = <name>.

Configuration

Config is stored in ~/.trilium-mcp/config.properties with 600 permissions:

~/.trilium-mcp/
  config.properties    # Created by --init

Security

Note content is user-created data that passes through the LLM context window. This server applies defense-in-depth mitigations:

• Random content boundaries — Each note_get_content response generates a cryptographically random boundary string (via SecureRandom). Note body content is wrapped with this boundary so the LLM can distinguish note data from system structure. An attacker cannot embed the boundary in a note to escape the content region.
• Security context preamble — Every sanitized response includes a leading block instructing the LLM to treat bounded content as data only.
• Rate limiting — Client-side sliding window rate limiter prevents runaway API calls.
• Input validation — Required parameters are validated before requests are sent. Missing or blank values return a clear error rather than making a malformed API call.
• Config protection — The config directory uses rwx------ permissions; the config file uses rw-------. The ETAPI token is never logged.

Architecture

Claude Code  <--stdio (JSON-RPC)-->  trilium-mcp.jar  <--HTTP-->  TriliumNext ETAPI
                                            |
                                    ~/.trilium-mcp/
                                      config.properties

• Transport — stdio (Claude Code spawns the server as a subprocess)
• Auth — static ETAPI token sent as the Authorization header
• Logging — all logs go to stderr (stdout is reserved for MCP JSON-RPC)

Development

# build
mvn clean package -q

# run tests
mvn test

# run init
java -jar target/trilium-mcp-1.0.0.jar --init

# run server (blocks on stdio — use with Claude Code or an MCP client)
java -jar target/trilium-mcp-1.0.0.jar

Project structure

src/main/java/com/trilium/mcp/
  TriliumMcpServer.java        # Entry point, server bootstrap, tool registration
  TriliumAuth.java             # Config loading, --init flow, Claude registration
  TriliumClient.java           # ETAPI HTTP client
  ContentSanitizer.java        # Prompt injection mitigations
  RateLimiter.java             # Sliding window rate limiter
  ResultHelper.java            # Response serialisation helpers
  tools/
    NoteTools.java             # note_get, note_get_content, note_create, note_update,
                               #   note_set_content, note_delete, note_export
    SearchTools.java           # search_notes, search_by_label, search_fulltext
    AttributeTools.java        # attribute_list, attribute_create, attribute_update,
                               #   attribute_delete, attribute_bulk_set
    NavigationTools.java       # get_children, get_note_tree, get_related_notes,
                               #   get_backlinks, get_note_path
    BranchTools.java           # branch_move, branch_clone, branch_reorder
    SystemTools.java           # app_info, trigger_backup, get_day_note
    OntologyTools.java         # list_projects, get_project, list_domains, get_domain,
                               #   get_ssl_expiring, list_unhealthy
    OntologyWriteTools.java    # create_deployment, create_incident, resolve_incident,
                               #   update_container_status, refresh_dashboard, add_runbook

src/test/java/com/trilium/mcp/
  TriliumAuthTest.java         # Config loading, path resolution
  TriliumClientTest.java       # HTTP client, request construction
  ContentSanitizerTest.java    # Boundary wrapping, preamble generation
  RateLimiterTest.java         # Rate limit enforcement
  ResultHelperTest.java        # Response serialisation helpers

License

MIT