TriliumNext MCP Server

A Model Context Protocol (MCP) server for interacting with TriliumNext via its ETAPI. Enables LLMs to create, read, update, and organize notes — including embedding images and files directly into note content.

Contents

• Features

• Installation

• Configuration — CLI, env vars, config file

• Logging — what gets logged, where it goes, how to tune it

• Metrics — Prometheus /metrics endpoint, auth modes, exposed series

• Available Tools

• Embedding Images and Files

• Multi-tenant HTTP deployment — run one server for many users

  • Architecture

  • Quick start (Docker) / (local)

  • HTTP endpoints · Error responses · Request body size limits

  • Connecting clients — Claude Desktop, Claude Code, SDK

  • JWT / OIDC gateway auth · CORS · Rate limiting

  • StreamableHTTP transport — newer MCP transport alongside /sse

  • Per-tenant audit + metrics

  • SSRF configuration · Reverse-proxy

  • Security model · Troubleshooting

• Debugging with MCP Inspector

• Development — build, test, docker

• Getting an ETAPI Token

Features

• 19 tools across 8 categories for full note management, search, organization, attachments, revisions, and system operations (consolidated from 35 in v1 — see Migrating from v1)

• MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, title) on every tool for better approval-dialog UX in clients that surface them

• Inline image and file embedding — attach images and files when creating or updating notes in a single tool call

• Data URL support — pass image/file data as raw base64 or data: URLs

• Four content modes on write_note — metadata, replace, append, and edit (search/replace or unified diff)

• Markdown support — write in markdown, stored as HTML automatically

• Image-aware content retrieval — get_note returns embedded images as MCP image blocks alongside the note body

• Support for STDIO, HTTP/SSE, and StreamableHTTP transports, including multi-tenant mode where each client brings its own Trilium URL + ETAPI token

• Pluggable gateway auth — none, shared-secret bearer, or JWT/OIDC (HS256 secrets + JWKS for RS256/ES256/EdDSA)

• CORS for browser-based MCP clients, in-process rate limiting per IP + per gateway token, and Prometheus metrics with optional per-principal labels

• Flexible configuration via CLI, environment variables, or config file

• TypeScript with full type safety

Installation

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

Adding to Claude Code

claude mcp add trilium node /path/to/triliumnext-mcp/dist/index.js \
  --scope user \
  -e TRILIUM_TOKEN=<your_etapi_token> \
  -e TRILIUM_URL=<your_trilium_url_e.g._https://trilium.example.com/etapi>

This adds the server at user scope (available across all repositories) in your ~/.claude.json.

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

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)

• --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

Environment Variables

export TRILIUM_URL=http://localhost:37740/etapi
export TRILIUM_TOKEN=your-etapi-token
export TRILIUM_TRANSPORT=stdio
export TRILIUM_HTTP_PORT=3000
export TRILIUM_MAX_POST_BYTES=500mb  # SSE POST body cap; see "Request body size limits"

# Multi-tenant (see section below):
export TRILIUM_MULTI_TENANT=true
export TRILIUM_GATEWAY_AUTH=bearer
export TRILIUM_GATEWAY_TOKENS=tok1,tok2
export TRILIUM_URL_ALLOWLIST=notes.example.com,trilium.internal
export TRILIUM_ALLOW_PRIVATE_URLS=false

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
}

Logging

The server emits one line per significant event — server startup, MCP tools/list, every tools/call (with timing and outcome), and every HTTP request when running over SSE. By default logs are human-readable text; flip to JSON for log shippers.

Where logs go

The output stream is chosen by transport, so logs never collide with the MCP wire protocol:

Claude Desktop and Claude Code surface stdio servers' stderr in their MCP logs panel, so you'll see these events there with no extra setup.

Tuning

Two env vars (defaults shown):

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.

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.

What's never logged

• ETAPI tokens, gateway bearer tokens, or any value of a field matching /token|password|secret|authorization|api[_-]?key/i

• Note bodies, attachment bytes, search results, or any field named content, text, body, data, attachment, blob, html, markdown — replaced with <string len=N> / <array len=N> / <object> shape descriptors at debug, omitted entirely at info

• Full Trilium URLs (which can theoretically embed credentials) — only the hostname is logged

Quick recipes

Silence the server (e.g. when invoking under a noisy test harness):

LOG_LEVEL=silent triliumnext-mcp --token "$TRILIUM_TOKEN"

Tee structured logs into a file while still seeing them in the terminal:

LOG_FORMAT=json triliumnext-mcp --transport http --token "$TRILIUM_TOKEN" \
  | tee >(jq -c . > /var/log/triliumnext-mcp.jsonl)

Find every failing tool call from the last run:

LOG_FORMAT=json triliumnext-mcp --transport http --token "$TRILIUM_TOKEN" \
  | jq -c 'select(.event=="tool_call" and .ok==false)'

Watch one tenant's activity in a multi-tenant deployment (correlate by SSE session id):

docker logs -f triliumnext-mcp | grep "session=2f1c"

Metrics

The server can expose a Prometheus-compatible GET /metrics endpoint on the SSE gateway. Off by default, opt in with --metrics or TRILIUM_METRICS=true. HTTP transport only — stdio mode has no listener, and the flag is ignored there with a warning.

Enabling

# Reuse the gateway bearer (default; same token that protects /sse)
node dist/index.js \
  --transport http \
  --multi-tenant \
  --gateway-token "$GATEWAY_TOKEN" \
  --metrics

Same thing via env:

TRILIUM_TRANSPORT=http \
TRILIUM_MULTI_TENANT=true \
TRILIUM_GATEWAY_TOKENS=$GATEWAY_TOKEN \
TRILIUM_METRICS=true \
  node dist/index.js

Auth modes

Selected with --metrics-auth <mode> or TRILIUM_METRICS_AUTH. Default is gateway.

If you ask for --metrics-auth gateway but --gateway-auth=none, there's no bearer to reuse — the server falls back to --metrics-auth=none and prints a startup warning so the behavior is explicit. If you set --metrics-auth bearer without providing any --metrics-token, startup fails fast.

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.

Reverse-proxy hardening

/metrics is served on the same listener and port as /sse (port 3000 by default). If you don't want public scrapers hammering the auth check, gate /metrics at the reverse proxy and only let your monitoring network through.

Caddy:

mcp.example.com {
    @metrics path /metrics
    handle @metrics {
        # only Prometheus can even reach /metrics; everyone else gets 404
        @allowed remote_ip 10.0.0.0/8 192.168.0.0/16
        handle @allowed {
            reverse_proxy 127.0.0.1:3000
        }
        respond 404
    }
    handle {
        reverse_proxy 127.0.0.1:3000 {
            flush_interval -1
        }
    }
}

nginx:

location = /metrics {
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    proxy_pass http://127.0.0.1:3000;
}

This is defense-in-depth on top of the bearer auth — useful because metrics endpoints are routinely scanned by attackers, and a misconfigured --metrics-auth=none would otherwise leak operational data to anyone who finds the URL.

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'

Exposed series

All series are namespaced triliumnext_mcp_*. Histogram buckets are in seconds.

Cardinality and what's intentionally NOT a label

• No session label. SSE session ids are unbounded and per-connection. Use logs (which carry session=…) for per-session investigation; use metrics for fleet-level rollups.

• No tenant / Trilium-host label. Same reason — and avoids putting tenant identifiers into a scrape surface that may have different access controls than the logs.

• No raw path for unknown routes. Random scanners / typo'd URLs collapse to unknown, so a probe storm can't blow up cardinality.

Useful PromQL

Tool error rate per tool:

sum by (tool) (rate(triliumnext_mcp_tool_calls_total{ok="false"}[5m]))
  /
sum by (tool) (rate(triliumnext_mcp_tool_calls_total[5m]))

p95 tool-call latency:

histogram_quantile(
  0.95,
  sum by (tool, le) (rate(triliumnext_mcp_tool_call_duration_seconds_bucket[5m]))
)

SSE connect failures by reason:

sum by (reason) (rate(triliumnext_mcp_sse_connect_failures_total[5m]))

Available Tools

The server exposes 19 tools, down from 35 in v1. The trim (see issue #6) improves reliability on clients that pre-load only a subset of a server's tools (claude.ai web, Cursor's 40-tool cap), and consolidates near-duplicate operations behind a mode or action discriminator. Destructive verbs (delete_*) stay as their own tools by design. See Migrating from v1 below for the old→new mapping.

Notes (5 tools)

Search & Discovery (2 tools)

Organization (1 tool)

Attributes & Labels (3 tools)

Calendar & Journal (1 tool)

Attachments (4 tools)

Revisions (1 tool)

System (2 tools)

Migrating from v1

The tool surface was consolidated in a breaking release. The mapping from the old 35-tool surface to the current 19-tool surface:

Embedding Images and Files

When creating or updating notes, you can embed images and files directly in a single tool call using the images and files parameters.

Image Embedding

Pass an images array and reference them in your content with image:0, image:1, etc.:

{
  "tool": "create_note",
  "arguments": {
    "parentNoteId": "root",
    "title": "My Note",
    "type": "text",
    "content": "<p>Here is a photo:</p><img src=\"image:0\">",
    "images": [
      {
        "data": "iVBORw0KGgo...",
        "mime": "image/png",
        "filename": "photo.png"
      }
    ]
  }
}

In markdown mode, use ![alt text](image:0):

{
  "content": "# My Note\n\n![photo](image:0)\n\nSome text.",
  "format": "markdown",
  "images": [{ "data": "iVBORw0KGgo...", "mime": "image/png", "filename": "photo.png" }]
}

Images without a matching placeholder are automatically appended at the end of the content.

File Embedding

Pass a files array and reference them with file:0, file:1, etc.:

{
  "content": "<p>Download the report: <a href=\"file:0\">Report PDF</a></p>",
  "files": [
    {
      "data": "JVBERi0xLjQ...",
      "mime": "application/pdf",
      "filename": "report.pdf"
    }
  ]
}

Files without a matching placeholder are appended as download links.

Data URL Support

The data field accepts both raw base64 and data URLs. When a data URL is provided, the MIME type is automatically extracted (overriding the mime field):

{
  "images": [
    {
      "data": "data:image/png;base64,iVBORw0KGgo...",
      "mime": "ignored-when-data-url-is-used",
      "filename": "screenshot.png"
    }
  ]
}

Content Update Modes

The write_note tool selects behavior via mode:

1. "metadata" — update title/type/mime only (no content change)

2. "replace" — overwrite content entirely with content. Supports images/files embedding and markdown conversion.

3. "append" — fetch existing content and concatenate content at the end. Supports images/files embedding and markdown conversion.

4. "edit" — apply changes (array of {old_string, new_string}) OR patch (unified diff) to existing content. Operates on stored HTML; cannot be combined with format="markdown" or images/files.

write_attachment follows the same shape with "metadata", "replace", and "edit" modes.

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.

What changes

With --multi-tenant:

1. Each SSE connection MUST supply its own Trilium credentials via HTTP headers, as an atomic pair:

   • X-Trilium-Url — the client's Trilium base URL

   • X-Trilium-Token — the client's ETAPI token

2. A per-connection TriliumClient is created — connections are isolated; one user's tool calls never hit another's Trilium.

3. Credentials are verified at connect time by calling /etapi/app-info (with a 10s timeout). A bad token fails fast with a 401 on the SSE handshake, not with silent tool-call errors later.

4. A gateway bearer token is required (--gateway-auth bearer, enabled by default in multi-tenant mode). Clients authenticate to you with a shared secret you hand out.

5. Client-supplied URLs are SSRF-checked. By default, hostnames that resolve to private/loopback/link-local IPs (including cloud metadata 169.254.169.254) are rejected. Adjust with --trilium-url-allowlist or --allow-private-urls.

Startup-supplied TRILIUM_URL / TRILIUM_TOKEN are rejected in multi-tenant mode. The server will refuse to start if either is set alongside --multi-tenant. This prevents a subtle token-leak where a client sending only one header would cause the operator's default to be mixed with client-supplied values.

Architecture

                  ┌───────────────────────────────────┐
   Client A ─────►│ /sse                              │   ┌────────────────┐
   (Auth: Bearer  │   1. gateway bearer check          │──►│ Trilium A      │
    X-Trilium-*)  │   2. SSRF guard on X-Trilium-Url  │   │ (notes-a.tld)  │
                  │   3. validate via /etapi/app-info │   └────────────────┘
   Client B ─────►│   4. new TriliumClient (per conn) │   ┌────────────────┐
                  │   5. new MCP Server (per conn)    │──►│ Trilium B      │
                  │                                   │   │ (notes-b.tld)  │
   Client N ─────►│ sessions: Map<sessionId, Session> │   └────────────────┘
                  │                                   │           ...
                  │ POST /message?sessionId=<uuid>    │
                  │   routes to the right session     │
                  │                                   │
                  │ GET /health  (no auth)            │
                  └───────────────────────────────────┘

Each SSE connection owns an independent Server + TriliumClient. Tool handlers close over the client, so tenant isolation is a property of the code, not something to enforce per-request.

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.

Quick start (local)

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

HTTP endpoints

Connecting clients

Any MCP client that can attach custom HTTP headers to an SSE connection will work.

Smoke test with curl:

curl -N \
  -H "Authorization: Bearer $MCP_GATEWAY_TOKEN" \
  -H "X-Trilium-Url: https://notes.example.com" \
  -H "X-Trilium-Token: $YOUR_ETAPI_TOKEN" \
  http://mcp-server.example.com:3000/sse

On success you'll see the endpoint SSE event, followed by message events as your client POSTs to /message.

Claude Desktop via mcp-remote:

Claude Desktop speaks stdio, so bridge it through mcp-remote which can carry custom headers to a remote SSE server. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trilium": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.example.com/sse",
        "--header", "Authorization: Bearer YOUR_GATEWAY_TOKEN",
        "--header", "X-Trilium-Url: https://notes.example.com",
        "--header", "X-Trilium-Token: YOUR_ETAPI_TOKEN"
      ]
    }
  }
}

Claude Code (native SSE):

claude mcp add trilium --scope user \
  --transport sse https://mcp.example.com/sse \
  --header "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  --header "X-Trilium-Url: https://notes.example.com" \
  --header "X-Trilium-Token: YOUR_ETAPI_TOKEN"

TypeScript SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

const transport = new SSEClientTransport(new URL('https://mcp.example.com/sse'), {
  requestInit: {
    headers: {
      Authorization: `Bearer ${GATEWAY_TOKEN}`,
      'X-Trilium-Url': 'https://notes.example.com',
      'X-Trilium-Token': ETAPI_TOKEN,
    },
  },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

StreamableHTTP transport

In addition to the older HTTP+SSE transport (GET /sse + POST /message), this server exposes the newer StreamableHTTP transport at GET|POST|DELETE /mcp on the same port. StreamableHTTP is the direction MCP is heading — single endpoint, session id in a header instead of a query string, optional resumability via Last-Event-ID. Both transports run side-by-side; clients can pick whichever the SDK they ship supports.

Initialize handshake (POST /mcp):

curl -X POST https://mcp.example.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Trilium-Url: https://notes.example.com" \
  -H "X-Trilium-Token: $ETAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2024-11-05","capabilities":{},
                 "clientInfo":{"name":"my-app","version":"1.0.0"}}}'

The response carries an MCP-Session-Id header. Subsequent requests echo it back:

curl -X POST https://mcp.example.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Session-Id: <sid>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

DELETE /mcp with the session id closes the session cleanly. The gateway-auth / SSRF / rate-limit / Trilium-validation pipeline is identical to /sse — switching transports never changes the security surface.

TypeScript SDK:

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://mcp.example.com/mcp'), {
  requestInit: {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-Trilium-Url': 'https://notes.example.com',
      'X-Trilium-Token': ETAPI_TOKEN,
    },
  },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

JWT / OIDC gateway auth

For per-user identity, use --gateway-auth jwt instead of bearer. Tokens are validated for signature, expiration (exp), not-before (nbf), and (optionally) issuer + audience. The authenticated principal claim (default sub) is threaded into every audit log line and — opt-in — into metric labels.

HS256 shared secret(s):

node dist/index.js \
  --transport http \
  --multi-tenant \
  --gateway-auth jwt \
  --jwt-secret "$JWT_SHARED_SECRET" \
  --jwt-issuer "https://idp.example.com" \
  --jwt-audience "mcp-gateway"

--jwt-secret is repeatable so you can roll secrets: deploy the new one alongside the old, then drop the old once all issuers have rotated.

RS256 / ES256 / EdDSA via JWKS:

node dist/index.js \
  --transport http --multi-tenant \
  --gateway-auth jwt \
  --jwt-jwks-url "https://idp.example.com/.well-known/jwks.json" \
  --jwt-issuer "https://idp.example.com" \
  --jwt-audience "mcp-gateway"

The JWKS URL is fetched on demand and cached; key rotation works automatically as the IdP publishes new keys.

Customize the principal claim:

--jwt-principal-claim email   # use the email claim instead of sub

Env equivalents: TRILIUM_JWT_SECRETS (CSV), TRILIUM_JWT_JWKS_URL, TRILIUM_JWT_ISSUER, TRILIUM_JWT_AUDIENCE, TRILIUM_JWT_PRINCIPAL_CLAIM. Validation: --gateway-auth jwt requires at least one secret OR a JWKS URL, else startup fails.

Algorithms accepted (default set): HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 EdDSA. alg=none is always rejected.

CORS

Off by default. For browser-based clients, allow specific origins:

--cors-origin https://app.example.com --cors-origin https://admin.example.com
# or wildcard (echoes Origin so credentials still work):
--cors-origin '*'

Env: TRILIUM_CORS_ORIGINS=https://a.example.com,https://b.example.com. Preflight (OPTIONS) responses allow Authorization, X-Trilium-Url, X-Trilium-Token, MCP-Session-Id, and Content-Type by default. The server never emits literal Allow-Origin: * even in wildcard mode — it always echoes the request Origin, because browsers reject wildcards with credentials.

Rate limiting

In-process token-bucket limiter, applied per remote IP and per gateway bearer/JWT token (whichever appears in Authorization). Both axes are enforced independently — exceeding either limit returns 429 rate_limited with a Retry-After header.

--rate-limit-rps 10 --rate-limit-burst 30

Env: TRILIUM_RATE_LIMIT_RPS, TRILIUM_RATE_LIMIT_BURST. /health is never rate-limited (cheap liveness). /metrics is rate-limited like everything else.

This is in-process, not a Redis-backed distributed limiter — multi-replica deployments should also limit at the reverse proxy, with this server's limits as defense-in-depth.

Per-tenant audit + metrics

With --gateway-auth jwt, every audit log line carries the authenticated principal field — both tool_call and mcp_session_opened/sse_connected events. That gives you per-user tool usage in your log shipper without any extra work.

For Prometheus, the per-principal counter is opt-in for cardinality safety:

--metrics --metrics-include-principal

Env: TRILIUM_METRICS_INCLUDE_PRINCIPAL=true. When on, a new series appears:

# HELP triliumnext_mcp_tool_calls_by_principal_total Per-principal tool invocation counter…
# TYPE triliumnext_mcp_tool_calls_by_principal_total counter
triliumnext_mcp_tool_calls_by_principal_total{principal="alice@example.com",tool="search_notes",ok="true",error="none"} 12

Cardinality scales as principals × tools × outcomes. Only enable when your principal namespace is bounded (e.g., a known IdP user list). The base tool_calls_total series stays principal-free and is always safe to enable.

SSRF configuration

Error responses

All errors are application/json with an error string. Common responses on GET /sse:

On POST /message:

Request body size limits

The HTTP/SSE transport caps each MCP JSON-RPC POST body at 500 MB by default. Tune it with --max-post-bytes <size> or TRILIUM_MAX_POST_BYTES (e.g. 100mb, 2gb, or a raw byte count). On stdio there is no equivalent cap — your shell / OS pipe buffers are the limit.

Why this exists, and a few caveats worth knowing:

• The MCP SDK has its own internal 4 MB cap inside handlePostMessage. To honor anything larger, this server reads and JSON-parses the request body itself before handing it off, bypassing the SDK's read. If you fork or upgrade and bodies start failing at ~4 MB with 400 from the SDK, this read-and-pass-through is what's missing.

• Bodies are buffered in memory before dispatch. A 500 MB cap means a single connection can ask for 500 MB of heap. On a multi-tenant deployment, set the cap to the smallest value your largest legitimate attachment needs.

• Attachments are base64-encoded over JSON-RPC, which inflates payload size by ~33%. A 100 MB binary becomes ~134 MB on the wire.

• 413 is returned as soon as we can detect the overrun — either from Content-Length upfront (no body drain) or mid-stream once accumulated bytes exceed the cap. Chunked uploads without Content-Length still get capped via the streaming check.

• Reverse proxies have their own limits. Nginx defaults to client_max_body_size 1m; bump it (client_max_body_size 600m; or similar) or large requests die at the proxy with 413 before they reach this server. Caddy has no default cap.

Reverse-proxy (TLS termination)

Caddy — simplest setup, automatic Let's Encrypt:

mcp.example.com {
    # preserve the client's Authorization + X-Trilium-* headers (default behavior)
    reverse_proxy 127.0.0.1:3000 {
        # SSE needs large/indefinite response buffering disabled
        flush_interval -1
    }
}

nginx — explicit SSE tuning:

server {
    listen 443 ssl http2;
    server_name mcp.example.com;
    # ssl_certificate / ssl_certificate_key configured elsewhere

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # SSE essentials
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 24h;
    }
}

Make sure the proxy passes through Authorization, X-Trilium-Url, X-Trilium-Token. Both examples above do by default.

Health check

GET /health returns {"status":"ok"} with no auth required. Used by the Docker HEALTHCHECK; also useful for load-balancer probes.

Security model

• Gateway auth (who can connect at all) is an operator-issued shared bearer token. Constant-time comparison, tokens stored as SHA-256 hashes at startup.

• Backend auth (which Trilium to talk to) is each client's own ETAPI token. It's only ever used to construct that client's TriliumClient; it's never logged.

• Creds are validated at connect time with a 10-second timeout, so a bad or slow Trilium target fails the SSE handshake instead of hanging the connection.

• No TLS in-process. Use a reverse proxy. The server listens on plain HTTP and expects to run behind one.

• Per-principal identity is available via --gateway-auth jwt (above). When you need to attribute actions to specific users, prefer JWT over a shared bearer token — the authenticated principal threads automatically into audit logs and (opt-in) into per-principal metric labels.

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.

Debugging with MCP Inspector

MCP Inspector provides a web UI for testing tools interactively:

TRILIUM_URL=http://localhost:37740/etapi TRILIUM_TOKEN=your-token npm run inspector

Opens at http://localhost:6274 where you can browse tools, execute calls, and inspect responses.

Development

Prerequisites

• Node.js 20+

• npm

• Docker (for integration tests)

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 .

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

License

MIT