trilium-mcp-proxy: connect MCP clients to Trilium with just a URL and your password

[Marceltov]

Since 0.106, Trilium ships its own MCP server at /mcp (Options → AI / LLM → MCP server). Thanks to everyone who built it. I use it daily to let Claude maintain a wiki in my Trilium.

Connecting a client means minting an ETAPI token under Options → ETAPI, copying it, and adding it to the client as an Authorization: Bearer … header. That works, but it's a chore for every new client, device or reinstall, and in local clients like Claude Code the token ends up in plain text in the MCP config file, with full access to your notes.

I wanted it to be as simple as adding any other OAuth connector, so I wrote a small proxy that puts an OAuth login in front of the built-in server. Connecting becomes: paste a short URL, log in with your Trilium password, done. No token to mint, and none sitting in a config file.

trilium-mcp-proxy · source on GitHub

Setup, before and after

Directly against the built-in server:

# first: Options → ETAPI → Create new token, copy it
claude mcp add --transport http trilium https://trilium.example.org/mcp \
  --header "Authorization: Bearer <your ETAPI token>" -s user

Through the proxy:

claude mcp add --transport http trilium https://trilium-mcp-proxy.example.org/mcp -s user
# then /mcp → Authenticate, and sign in with your Trilium password

On claude.ai it's the same: Add custom connector, paste the URL, sign in. No header to fill in.

What else it does

• No ETAPI token in your client config. The client stores only OAuth tokens. Those work nowhere but your proxy, the access token expires after an hour, and you can revoke them.
• The proxy mints an ETAPI token for each login itself, listed under Options → ETAPI. Delete it there and that client is cut off.
• Every /mcp request goes to Trilium unchanged, with only Authorization swapped. The tools are exactly Trilium's, so new tools arrive with Trilium updates, not with a proxy release.
• Two-factor login works: the login page takes your TOTP code (or a recovery code) too.
• Optional MCP_INSTRUCTIONS: standing instructions every client reads when it connects (I use it to point Claude at my wiki's schema note).
• Clients that already send an ETAPI token keep working through the proxy.

How it works

sequenceDiagram
    participant C as MCP client
    participant P as trilium-mcp-proxy
    participant T as Trilium

    C->>P: connect with the URL
    P->>T: you log in once with your Trilium password
    T-->>P: ETAPI token for this client
    C->>P: MCP requests
    P->>T: same requests, with the ETAPI token

Loading

The step-by-step OAuth flow (and how it would look inside Trilium) is in #12309.

Your password stays on your server

The proxy runs next to Trilium, and the login page is its own. The password goes from your browser to the proxy and on to Trilium's /etapi/auth/login. The proxy never stores or logs it, and the MCP client (claude.ai included) never sees it or the ETAPI token. It only gets opaque OAuth tokens that work nowhere but your proxy.

Running it

Next to Trilium in your compose file:

  trilium-mcp-proxy:
    image: ghcr.io/marceltov/trilium-mcp-proxy:latest
    restart: unless-stopped
    environment:
      TRILIUM_SERVER_URL: http://trilium:8080
      MCP_BASE_URL: https://trilium-mcp-proxy.example.org   # public URL, behind your TLS reverse proxy
      MCP_OAUTH_SECRET: ${MCP_OAUTH_SECRET}                 # openssl rand -hex 32
    volumes:
      - mcp-proxy-oauth:/data
    ports:
      - "8081:8081"

Next step: OAuth in Trilium itself

The proxy is a convenience, not a requirement: everything works with a token header too. It doesn't add, rename or filter tools; it's a thin login in front of what Trilium already has.

The better place for this login is Trilium itself: no extra container, your normal Trilium login page (password, TOTP or OpenID), and connected clients listed under Options → ETAPI. I've proposed exactly that in #12309 and would like to build it. Thoughts there are very welcome. Once it lands, the proxy can retire.

If you use Claude Code, trilium-plugin adds skills on top (templates, journal notes, attributes, export) and connects either directly with a token or through the proxy.

AGPL-3.0-or-later. Feedback and issues welcome. I'd especially like to hear from anyone running it with clients other than Claude.