Compose examples¶

trilium-mcp runs next to a Trilium server you already have. Pick the example that matches how Trilium is deployed: in the same compose file, or as its own compose project. Both are in the repo's examples/ directory.

Don't have Trilium yet?¶

trilium-mcp connects to an existing Trilium server. To set one up, follow Trilium's own guide to running Trilium with Docker, then come back here. Trilium's documentation covers the other ways to install it.

In Trilium's compose file¶

Add the trilium-mcp service and the mcp-oauth volume to the docker-compose.yaml that runs Trilium. Its settings go in a separate trilium-mcp.env, so they don't mix with the .env Trilium may already use. Copy trilium-mcp.env.example to trilium-mcp.env next to the compose file, adjust it, and run docker compose up -d trilium-mcp.

docker-compose.yamltrilium-mcp.env

# Add trilium-mcp and its volume to the compose file that runs Trilium.
# Copy trilium-mcp.env.example to trilium-mcp.env next to it, then:
#   docker compose up -d trilium-mcp
services:
  trilium:
    # ... your existing Trilium service ...

  trilium-mcp:
    image: ghcr.io/marceltov/trilium-mcp:latest
    container_name: trilium-mcp
    restart: unless-stopped
    env_file: trilium-mcp.env
    volumes:
      # OAuth logins survive container updates (unused with tokens only).
      - mcp-oauth:/data
    ports:
      - "8081:8081"

volumes:
  mcp-oauth:

# Trilium's service name in this compose file, port 8080.
TRILIUM_SERVER_URL=http://trilium:8080

# Optional: enable OAuth login. Leave both empty for ETAPI tokens only.
# Public HTTPS address of this server, behind your reverse proxy.
MCP_BASE_URL=
# Encrypts stored logins. Generate once with: openssl rand -hex 32
MCP_OAUTH_SECRET=

# Optional: accept only these Host headers, comma-separated host[:port].
MCP_ALLOWED_HOSTS=

# Optional: set to true to also serve a ChatGPT Custom GPT Action.
CHATGPT_ACTIONS=

Both services share the compose network, so trilium resolves to your Trilium container.

As a separate compose project¶

Use this when you'd rather keep trilium-mcp out of Trilium's compose file. It joins the Docker network Trilium is already on. Put the files in their own folder, copy .env.example to .env, adjust it, and run docker compose up -d.

docker-compose.yaml.env

# trilium-mcp next to an existing Trilium, as its own compose project.
# Copy .env.example to .env, adjust it, then: docker compose up -d
services:
  trilium-mcp:
    image: ghcr.io/marceltov/trilium-mcp:latest
    container_name: trilium-mcp
    restart: unless-stopped
    env_file: .env
    volumes:
      # OAuth logins survive container updates (unused with tokens only).
      - mcp-oauth:/data
    ports:
      - "8081:8081"
    networks:
      - trilium

networks:
  # The Docker network your Trilium container is already on.
  trilium:
    external: true
    name: ${TRILIUM_NETWORK:?set TRILIUM_NETWORK in .env}

volumes:
  mcp-oauth:

# Docker network your Trilium container is on; find it with `docker network ls`.
# A compose project named "trilium" creates "trilium_default".
TRILIUM_NETWORK=trilium_default

# Trilium's address on that network: its service or container name, port 8080.
TRILIUM_SERVER_URL=http://trilium:8080

# Optional: enable OAuth login. Leave both empty for ETAPI tokens only.
# Public HTTPS address of this server, behind your reverse proxy.
MCP_BASE_URL=
# Encrypts stored logins. Generate once with: openssl rand -hex 32
MCP_OAUTH_SECRET=

# Optional: accept only these Host headers, comma-separated host[:port].
MCP_ALLOWED_HOSTS=

# Optional: set to true to also serve a ChatGPT Custom GPT Action.
CHATGPT_ACTIONS=

To find TRILIUM_NETWORK, run docker network ls, or docker inspect <trilium container> to see which network Trilium is on. TRILIUM_SERVER_URL uses Trilium's service or container name on that network.

Turning on OAuth¶

In either example, fill in MCP_BASE_URL and MCP_OAUTH_SECRET in the env file and recreate the container with docker compose up -d. Once the file holds the secret, keep it private (chmod 600) and out of version control. Every setting is described under Configuration.