# BrainLLM MCP server

> Provides LLMs with persistent, self-hosted memory by using TriliumNext Notes as a structured knowledge base via the Model Context Protocol.

- Repository: https://github.com/miisodev/BrainLLM
- Page: https://hostedmcp.org/servers/miisodev/brainllm
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 13.3.2

## Install

### Claude Code

```sh
claude mcp add --env 'TRILIUM_BASE_URL=<TRILIUM_BASE_URL>' --env 'BRAINLLM_OAUTH_SECRET=<YOUR_BRAINLLM_OAUTH_SECRET>' --env 'BRAINLLM_OWNER_PASSWORD=<YOUR_BRAINLLM_OWNER_PASSWORD>' --env 'TRILIUM_ETAPI_TOKEN=<YOUR_TRILIUM_ETAPI_TOKEN>' --env 'TRILIUM_PASSWORD=<YOUR_TRILIUM_PASSWORD>' brainllm -- npx -y brainllm
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "brainllm": {
      "command": "npx",
      "args": [
        "-y",
        "brainllm"
      ],
      "env": {
        "TRILIUM_BASE_URL": "<TRILIUM_BASE_URL>",
        "BRAINLLM_OAUTH_SECRET": "<YOUR_BRAINLLM_OAUTH_SECRET>",
        "BRAINLLM_OWNER_PASSWORD": "<YOUR_BRAINLLM_OWNER_PASSWORD>",
        "TRILIUM_ETAPI_TOKEN": "<YOUR_TRILIUM_ETAPI_TOKEN>",
        "TRILIUM_PASSWORD": "<YOUR_TRILIUM_PASSWORD>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "brainllm": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "brainllm"
      ],
      "env": {
        "TRILIUM_BASE_URL": "<TRILIUM_BASE_URL>",
        "BRAINLLM_OAUTH_SECRET": "<YOUR_BRAINLLM_OAUTH_SECRET>",
        "BRAINLLM_OWNER_PASSWORD": "<YOUR_BRAINLLM_OWNER_PASSWORD>",
        "TRILIUM_ETAPI_TOKEN": "<YOUR_TRILIUM_ETAPI_TOKEN>",
        "TRILIUM_PASSWORD": "<YOUR_TRILIUM_PASSWORD>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"brainllm","type":"stdio","command":"npx","args":["-y","brainllm"],"env":{"TRILIUM_BASE_URL":"<TRILIUM_BASE_URL>","BRAINLLM_OAUTH_SECRET":"<YOUR_BRAINLLM_OAUTH_SECRET>","BRAINLLM_OWNER_PASSWORD":"<YOUR_BRAINLLM_OWNER_PASSWORD>","TRILIUM_ETAPI_TOKEN":"<YOUR_TRILIUM_ETAPI_TOKEN>","TRILIUM_PASSWORD":"<YOUR_TRILIUM_PASSWORD>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "brainllm": {
      "command": "npx",
      "args": [
        "-y",
        "brainllm"
      ],
      "env": {
        "TRILIUM_BASE_URL": "<TRILIUM_BASE_URL>",
        "BRAINLLM_OAUTH_SECRET": "<YOUR_BRAINLLM_OAUTH_SECRET>",
        "BRAINLLM_OWNER_PASSWORD": "<YOUR_BRAINLLM_OWNER_PASSWORD>",
        "TRILIUM_ETAPI_TOKEN": "<YOUR_TRILIUM_ETAPI_TOKEN>",
        "TRILIUM_PASSWORD": "<YOUR_TRILIUM_PASSWORD>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add brainllm --env 'TRILIUM_BASE_URL=<TRILIUM_BASE_URL>' --env 'BRAINLLM_OAUTH_SECRET=<YOUR_BRAINLLM_OAUTH_SECRET>' --env 'BRAINLLM_OWNER_PASSWORD=<YOUR_BRAINLLM_OWNER_PASSWORD>' --env 'TRILIUM_ETAPI_TOKEN=<YOUR_TRILIUM_ETAPI_TOKEN>' --env 'TRILIUM_PASSWORD=<YOUR_TRILIUM_PASSWORD>' -- npx -y brainllm
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.brainllm]
command = "npx"
args = ["-y", "brainllm"]

[mcp_servers.brainllm.env]
TRILIUM_BASE_URL = "<TRILIUM_BASE_URL>"
BRAINLLM_OAUTH_SECRET = "<YOUR_BRAINLLM_OAUTH_SECRET>"
BRAINLLM_OWNER_PASSWORD = "<YOUR_BRAINLLM_OWNER_PASSWORD>"
TRILIUM_ETAPI_TOKEN = "<YOUR_TRILIUM_ETAPI_TOKEN>"
TRILIUM_PASSWORD = "<YOUR_TRILIUM_PASSWORD>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'TRILIUM_BASE_URL=<TRILIUM_BASE_URL>' -e 'BRAINLLM_OAUTH_SECRET=<YOUR_BRAINLLM_OAUTH_SECRET>' -e 'BRAINLLM_OWNER_PASSWORD=<YOUR_BRAINLLM_OWNER_PASSWORD>' -e 'TRILIUM_ETAPI_TOKEN=<YOUR_TRILIUM_ETAPI_TOKEN>' -e 'TRILIUM_PASSWORD=<YOUR_TRILIUM_PASSWORD>' brainllm npx -- -y brainllm
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "brainllm": {
      "command": "npx",
      "args": [
        "-y",
        "brainllm"
      ],
      "env": {
        "TRILIUM_BASE_URL": "<TRILIUM_BASE_URL>",
        "BRAINLLM_OAUTH_SECRET": "<YOUR_BRAINLLM_OAUTH_SECRET>",
        "BRAINLLM_OWNER_PASSWORD": "<YOUR_BRAINLLM_OWNER_PASSWORD>",
        "TRILIUM_ETAPI_TOKEN": "<YOUR_TRILIUM_ETAPI_TOKEN>",
        "TRILIUM_PASSWORD": "<YOUR_TRILIUM_PASSWORD>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `TRILIUM_BASE_URL` | yes | no | Base URL of the TriliumNext instance, e.g. http://localhost:8080 |
| `BRAINLLM_OAUTH_SECRET` | no | yes | Optional 32+ character deployment secret for signing OAuth tokens; rotate it to invalidate old tokens. |
| `BRAINLLM_OWNER_PASSWORD` | no | yes | Enables the OAuth 2.1 / CIMD endpoints required by claude.ai and other hosted Claude surfaces. This is the password entered on the consent screen when authorizing a client. |
| `TRILIUM_ETAPI_TOKEN` | no | yes | ETAPI token. Required unless TRILIUM_PASSWORD is set. Create one in Trilium under Options → ETAPI. |
| `TRILIUM_PASSWORD` | no | yes | Alternative to TRILIUM_ETAPI_TOKEN — BrainLLM mints a token on first start and caches it beside brainllm.json. |
| `BRAINLLM_ALLOW_UNAUTHENTICATED_HTTP` | no | no | Explicit trusted-network-only escape hatch for HTTP mode. Never enable on a public interface. |
| `BRAINLLM_LIVE_TOKEN` | no | no |  |
| `BRAINLLM_MODE` | no | no | core (default) exposes the 45 brain-aware tools; full additionally exposes the 33 raw ETAPI tools. |
| `BRAINLLM_PUBLIC_URL` | no | no | Override for the public origin when a proxy rewrites Host. Must exactly match the URL entered in the client. |
| `BRAINLLM_TRUST_PROXY` | no | no | Trust forwarded host/protocol headers for OAuth discovery only when a trusted reverse proxy sets them. |
| `BRAINLLM_TZ` | no | no | IANA timezone used to stamp dated notes, e.g. Africa/Johannesburg. Defaults to the host timezone. |

## FAQ

### What is BrainLLM?

BrainLLM is an MCP server that gives an LLM a real, persistent memory stored in TriliumNext Notes, a self-hosted open-source knowledge base.

### Does the LLM decide how to organize the memory?

No, the server enforces structure and policy. The model provides the content, but the server handles placement, naming, labels, and deduplication.

### Can multiple agents use the memory at once?

Yes, it supports multi-agent use by default. Write operations are serialized behind a process-wide FIFO lock to prevent racing, while reads remain fully parallel.

### How does it handle session continuity?

The model can use a single call to orient itself by loading previous session details, change logs, and everything touched since the last session.
