Trilium MCP

Prerequisites

• Node.js 20+
• npm
• Docker (for integration tests)

Installation

git clone https://github.com/perfectra1n/triliumnext-mcp
cd triliumnext-mcp
npm install
npm run build

Deploying with Docker / Compose

Add to docker-compose.multi-tenant.yml (already templated as commented-out entries in that file):

services:
  mcp-server:
    environment:
      - TRILIUM_METRICS=true
      # Default: reuse the gateway bearer. No new config needed.
      - TRILIUM_METRICS_AUTH=gateway
      # Or, give Prometheus its own rotatable credential:
      # - TRILIUM_METRICS_AUTH=bearer
      # - TRILIUM_METRICS_TOKENS=${PROMETHEUS_SCRAPE_TOKEN}

In Kubernetes, the equivalent is two env vars (TRILIUM_METRICS=true and TRILIUM_METRICS_AUTH) on the Deployment plus a ServiceMonitor with bearerTokenSecret pointing at the token Secret.

Multi-tenant HTTP deployment

By default the server is single-tenant: TRILIUM_URL and TRILIUM_TOKEN are loaded once at startup and every MCP client that connects talks to the same Trilium instance. That's fine for a personal setup, but if you want to run one MCP server process that serves multiple users, each with their own Trilium and their own ETAPI token, switch it into multi-tenant mode.

Quick start (Docker)

export MCP_GATEWAY_TOKEN=$(openssl rand -hex 32)
docker compose -f docker-compose.multi-tenant.yml up -d

Distribute MCP_GATEWAY_TOKEN to authorized clients. Put a TLS-terminating reverse proxy (nginx, Caddy, Traefik) in front of this container — bearer tokens in plaintext HTTP are unsafe.

Setup

npm install          # Install dependencies
npm run build        # Build TypeScript
npm test             # Run unit tests
npm run test:integration  # Run integration tests (starts Trilium in Docker)
npm run lint         # Run linter
npm run format       # Format code

Docker

Start Trilium and the MCP server:

TRILIUM_TOKEN=your-token docker compose up -d

Build the Docker image:

docker build -t triliumnext-mcp .

Example output

info level, text format (the default):

2026-05-12T18:16:21.098Z INFO  server_started transport=stdio
2026-05-12T18:16:33.937Z INFO  http_request method=GET path=/health status=200 duration_ms=2 remote=::1
2026-05-12T18:16:40.512Z INFO  sse_connected session=2f1c... host=notes.example.com
2026-05-12T18:16:40.871Z INFO  list_tools session=2f1c... count=19
2026-05-12T18:16:41.044Z INFO  tool_call session=2f1c... tool=search_notes duration_ms=42 ok=true
2026-05-12T18:16:42.110Z INFO  tool_call session=2f1c... tool=get_note duration_ms=11 ok=false error=trilium status=404 code=NOT_FOUND
2026-05-12T18:16:55.802Z INFO  sse_closed session=2f1c...

LOG_FORMAT=json:

{"ts":"2026-05-12T18:16:41.044Z","level":"info","event":"tool_call","session":"2f1c...","tool":"search_notes","duration_ms":42,"ok":true}

The session field is identical across sse_connected, every tool_call on that connection, and sse_closed, so you can correlate tool activity to its SSE session and (in multi-tenant mode) to its Trilium host.

Quick start (local)

npm run build
node dist/index.js \
  --transport http \
  --port 3000 \
  --multi-tenant \
  --gateway-token "$(openssl rand -hex 32)"

Configuration

Configuration precedence (highest to lowest): 1. CLI arguments 2. Environment variables 3. Configuration file (./trilium-mcp.json or ~/.trilium-mcp.json) 4. Default values

Environment Variables

```bash export TRILIUM_URL=http://localhost:37740/etapi export TRILIUM_TOKEN=your-etapi-token export TRILIUM_PUBLIC_URL=https://trilium.example.com # optional; web URL for note links (defaults to TRILIUM_URL without /etapi) export TRILIUM_TRANSPORT=stdio export TRILIUM_HTTP_PORT=3000 export TRILIUM_MAX_POST_BYTES=500mb # SSE POST body cap; see "Request body size limits"

Config File

Create trilium-mcp.json in the current directory or ~/.trilium-mcp.json:

{
  "url": "http://localhost:37740/etapi",
  "token": "your-etapi-token",
  "transport": "stdio",
  "httpPort": 3000
}

For multi-tenant HTTP deployments, the same precedence applies (CLI > env > file > default). Multi-tenant keys:

{
  "transport": "http",
  "httpPort": 3000,
  "multiTenant": true,
  "gatewayAuth": "bearer",
  "gatewayTokens": ["pick-a-long-random-token"],
  "urlAllowlist": ["notes.example.com", "trilium.internal"],
  "allowPrivateUrls": false
}

Sample Prometheus scrape config

scrape_configs:
  - job_name: triliumnext-mcp
    scheme: https
    static_configs:
      - targets: ['mcp.example.com']
    metrics_path: /metrics
    authorization:
      type: Bearer
      credentials: 'YOUR_GATEWAY_OR_METRICS_TOKEN'

SSRF configuration

CLI Arguments

npm install -g .
triliumnext-mcp --url http://localhost:37740/etapi --token YOUR_TOKEN

Options: - -u, --url <url> — Trilium ETAPI URL (default: http://localhost:37740/etapi) - -t, --token <token> — Trilium ETAPI token (required in single-tenant mode) - --public-url <url> — user-facing Trilium web URL used for the clickable note links returned to the user. Defaults to --url with /etapi stripped. Set this only when the MCP server reaches Trilium at a different address than the user's browser does (e.g. an internal ETAPI host behind a public reverse-proxy domain). - --transport <type> — Transport type: stdio or http (default: stdio) - -p, --port <port> — HTTP server port when using http transport (default: 3000) - --max-post-bytes <size> — max size of a single MCP JSON-RPC POST body on the SSE transport. Accepts raw bytes or suffixed values like 500mb / 1gb (default: 500mb). See Request body size limits. - -h, --help — Show help message

Multi-tenant HTTP options (see Multi-tenant HTTP deployment below): - --multi-tenant — each SSE client supplies its own Trilium URL + token - --gateway-auth <mode> — none or bearer (default: bearer when multi-tenant) - --gateway-token <token> — accepted bearer token (repeatable) - --trilium-url-allowlist <hosts> — comma-separated allowed hostnames for client URLs - --allow-private-urls — skip the private/loopback IP SSRF block

Event reference

Event names match the JSON error strings returned to the HTTP client where applicable, so a grep for a failure mode finds both the log line and the response.

HTTP endpoints

Getting an ETAPI Token

1. Open TriliumNext in your browser
2. Go to Options (gear icon) → ETAPI
3. Create a new ETAPI token
4. Copy the token and use it in your configuration

Troubleshooting

Connection immediately returns 401 unauthorized. Missing or malformed Authorization: Bearer. Check your client logs — some MCP clients strip non-standard headers on SSE.

Connection returns 401 trilium_auth_failed. The ETAPI token was rejected by Trilium. Test it directly: curl -H "Authorization: $TOKEN" https://trilium.example.com/etapi/app-info.

Connection returns 400 url_rejected with reason=private_address. You're pointing at a private/loopback IP (common in homelabs). Either add the hostname to --trilium-url-allowlist or pass --allow-private-urls.

Connection returns 504 trilium_validate_timeout. getAppInfo didn't respond within 10 seconds. Usually a DNS black hole, a firewall dropping packets, or Trilium is actually down.

Connection succeeds but tool calls hang. Reverse proxy is buffering SSE. Verify proxy_buffering off (nginx) / flush_interval -1 (Caddy).

/health returns 200 but clients get 502/504 from the proxy. Proxy can reach the MCP server, but the server can't reach Trilium from its own network namespace (e.g., Docker bridge vs. host). Check docker exec triliumnext-mcp wget -qO- http://trilium:8080/etapi/app-info.