Athena

A personal wiki your AI writes to, and you can browse yourself.

Athena puts an MCP server in front of Wiki.js. Your assistant searches the wiki, reads pages, and files new ones back: notes, documentation, whole conversations. Everything it writes is an ordinary Markdown page you can open, edit, and keep long after any particular model is gone.

Claude / ChatGPT / Cursor
        │  MCP over HTTPS
        ▼
   athena-mcp ──── search ──▶ Wiki.js (keyword) + Postgres (meaning)
        │          read ────▶ Wiki.js
        └────────  write ───▶ Wiki.js ──▶ athena-indexer ──▶ Postgres

Wiki.js holds the truth. The vector index only helps find things, and can be deleted and rebuilt at any time.

Quickstart

Local, in about five minutes. For anything on the internet, read Deploy to a server first.

git clone https://github.com/jannismilz/athena.git
cd athena
cp .env.example .env
$EDITOR .env          # fill in every CHANGE_ME, one per secret:
                      #   openssl rand -hex 32
docker compose up -d

Then:

1. Open Wiki.js and complete the setup wizard.

2. In Wiki.js: Administration → API, enable it, create a token, and put it in .env as WIKI_API_TOKEN.

3. docker compose up -d again to pick it up.

4. Open the dashboard and sign in with DASHBOARD_TOKEN.

Nothing publishes a port, so reach the services through your reverse proxy, or add a temporary ports: mapping while trying it out.

The first start downloads an embedding model of a few hundred MB. The indexer retries until it is ready, so embeddings looking unhealthy for a minute or two on first boot is expected.

Connect your AI

Everything is served from MCP_PUBLIC_URL, which must be a bare https:// origin with no path. Not /mcp.

Claude.ai → Settings → Connectors → Add custom connector

• URL: https://athena-mcp.example.com/mcp

• Leave client ID and secret empty. Athena registers the client itself.

• A browser page asks for a password. It is your MCP_TOKEN.

Cursor, Claude Desktop, and other header clients

{
  "mcpServers": {
    "athena": {
      "url": "https://athena-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
    }
  }
}

Tools

append_to_page is the one worth knowing about: adding a fact costs a paragraph, not a rewrite of the whole page.

Why it retrieves well. Exact terms hit the Wiki.js full-text index, vague questions hit the vector index, and results are fused with reciprocal rank fusion so neither source can bury the other. Chunks record the headings above them, so what comes back keeps its context. Every page an assistant touches is stamped with which one it was and when, taken from the authenticated client rather than from what the model claims about itself.

Dashboard

Its own service, on port 8082. Sign in with DASHBOARD_TOKEN; there is no token in any URL. For scripts, use a bearer header:

curl -H "Authorization: Bearer $DASHBOARD_TOKEN" \
  https://wiki.example.com/dashboard/api/metrics?days=30

The third row is the one that earns its place. Every entry is a page worth writing.

It is read-only twice over: it never writes, and it connects to Postgres as athena_readonly, a role holding SELECT and nothing else. Figures are aggregated in Postgres and cached, so a refresh costs almost nothing.

Deploy to a server

A 4 GB VPS runs everything, including the embedding model on CPU.

1. Host and firewall

sudo ufw default deny incoming && sudo ufw default allow outgoing
sudo ufw allow 22/tcp && sudo ufw allow 80/tcp && sudo ufw allow 443/tcp
sudo ufw enable

Install Docker, then create a user that owns the deployment:

sudo useradd --create-home --shell /bin/bash athena
sudo usermod -aG docker athena
sudo mkdir -p /srv/athena && sudo chown athena:athena /srv/athena

Run compose as that user, never with sudo, or the bind mounts end up owned by root. Membership of the docker group is equivalent to root on the host, so keep it small.

2. DNS

Two A records pointing at the host:

3. Configure

cd /srv/athena
git clone https://github.com/jannismilz/athena.git .
cp .env.example .env
chmod 600 .env        # it holds every secret

Set at minimum:

ATHENA_DATA_DIR=/srv/athena/data
POSTGRES_PASSWORD=...
MCP_TOKEN=...
DASHBOARD_TOKEN=...
DASHBOARD_DB_PASSWORD=...
MCP_PUBLIC_URL=https://athena-mcp.example.com
WIKI_PUBLIC_URL=https://wiki.example.com

4. Reverse proxy

No container publishes a port. Everything lives on the athena Docker network, which your proxy joins. Route these:

Forward X-Forwarded-For: the logins throttle per address, and without it every attempt looks like it came from the proxy.

Run nginx as a container joined to the athena network, as below, or on the host with a ports: mapping bound to 127.0.0.1.

server {
    listen 80;
    server_name wiki.example.com;

    location / {
        proxy_pass http://wikijs:3000;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
        client_max_body_size 100M;
        proxy_read_timeout 120s;
    }

    location /dashboard/ {
        proxy_pass http://dashboard:8082/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name athena-mcp.example.com;

    location / {
        proxy_pass http://mcp:8080;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # MCP streams responses. Without these, long tool calls appear to hang.
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}

Then issue certificates with certbot, or terminate TLS wherever you already do.

5. Start, then lock the wiki down

docker compose up -d && docker compose ps

Complete the Wiki.js wizard immediately. Until you do, anyone who finds the host can claim the admin account. Then, in Wiki.js:

• Groups → Guests: remove read access, unless you want the wiki public.

• Auth: turn off self-registration.

• API: enable it and create the token for WIKI_API_TOKEN.

6. Verify

curl -s https://athena-mcp.example.com/health

# Must reject unauthenticated calls:
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://athena-mcp.example.com/mcp
# expected: 401

Backups

One pg_dump is a complete backup. Wiki.js keeps pages, history, users, permissions, settings and the bytes of every uploaded file in Postgres. Uploads live in the assetData table; the files under data/wikijs/uploads are only a cache. Athena's activity log and search vectors are in a second database on the same server.

The backup container runs hourly. Each run dumps both databases, checks every dump is readable, keeps a local copy, pushes to your rclone destination, verifies the upload matches, and only then prunes. A failed run can never delete your last good backup.

docker compose run --rm backup now            # take one now
docker compose run --rm backup restore list   # see what exists
docker compose logs -f backup                 # watch the schedule

Configure it entirely in .env. Any rclone destination works: S3, Backblaze, Wasabi, MinIO, Hetzner. Leave BACKUP_REMOTE empty to keep backups on the host only.

Add a crypt remote and point BACKUP_REMOTE at it. The destination then only ever receives ciphertext, including file names.

BACKUP_REMOTE=crypt:
RCLONE_CONFIG_CRYPT_TYPE=crypt
RCLONE_CONFIG_CRYPT_REMOTE=s3:my-bucket/athena
RCLONE_CONFIG_CRYPT_PASSWORD=<rclone obscure ...>
RCLONE_CONFIG_CRYPT_PASSWORD2=<rclone obscure ...>

Keep both passwords in your password manager. Without them the backups are unreadable, including by you.

Restoring

Practise this before you need it. A restore nobody has run is a guess.

docker compose run --rm backup restore list
docker compose stop wikijs mcp indexer dashboard
docker compose run --rm backup restore run 2026-08-18T115529Z
docker compose start wikijs mcp indexer dashboard

It asks you to type the database name to confirm. restore fetch <stamp> downloads a backup without restoring it, and reports whether each dump is readable.

The search index repairs itself afterwards: the indexer re-reads every page and re-embeds anything whose content changed.

Configuration

Everything comes from the environment. Each service validates its own configuration at boot and exits with a list of what is wrong, so a typo fails immediately rather than at three in the morning.

The five secrets, all generated by you. No credential belonging to Claude, OpenAI or anyone else is ever stored in .env.

What runs

There is no separate vector database. Vectors live in Postgres, so one backup covers everything.

On ARM hosts the embeddings image is published for linux/amd64 only and will not run natively. Point EMBEDDINGS_PROVIDER=openai at an OpenAI-compatible endpoint such as Ollama instead.

Changing EMBEDDINGS_MODEL changes the vector width, and vectors from two models cannot be compared, so the indexer rebuilds the table and re-embeds every page. Wiki.js content is untouched.

Security

Each container receives only the credentials it uses. The dashboard gets neither POSTGRES_PASSWORD nor WIKI_API_TOKEN, so compromising it yields read access and nothing more. Check at any time:

docker inspect athena-dashboard -f '{{range .Config.Env}}{{println .}}{{end}}' | grep -iE 'PASSWORD|TOKEN'

• Unauthenticated MCP requests get 401 and no explanation.

• Both login paths throttle after 5 failures per address; a login link burns after 3 attempts.

• Dashboard sessions are signed cookies carrying an expiry and a nonce, never the token. HttpOnly, SameSite=Strict, and cross-site posts are refused.

• Secret comparisons are constant time.

• Proxy headers are trusted only from loopback, so a remote client cannot forge its address to escape a throttle.

• Containers run as a non-root user.

Deliberately absent: per-tool permissions. Any authenticated client can call every tool, including delete_page. Wiki.js keeps page history so a delete is recoverable, but treat MCP_TOKEN as full write access to your wiki. Athena also assumes a single owner; Wiki.js has its own users for reading the wiki.

MCP_TOKEN works two ways, because AI clients authenticate two ways.

Header clients such as Cursor and Claude Desktop send Authorization: Bearer <MCP_TOKEN>. That is the whole mechanism.

Claude.ai in the browser cannot do that. Its custom connectors only support OAuth, and the MCP specification requires dynamic client registration, so a server that accepts browser Claude has to be an authorization server. Athena implements one:

1. Claude registers itself and receives a generated client id. No secret of yours is involved.

2. Claude sends you to a login page on your own server.

3. You type MCP_TOKEN as the password. That is the human approval step.

4. Athena issues Claude tokens that Athena minted itself.

Those tokens are written to data/mcp/oauth-state.json, never to .env. Revoke them with:

rm data/mcp/oauth-state.json && docker compose restart mcp

If you never use browser Claude, ignore all of this. The bearer path does not touch it.

Operations

docker compose logs -f mcp
curl -s localhost:8081/stats | python3 -m json.tool

# Force a full reconciliation
docker compose exec -T indexer bun -e 'await fetch("http://127.0.0.1:8081/sync",{method:"POST"})'

Upgrading. Always back up first: Wiki.js runs its own migrations on start, and those are not reversible by stopping the container.

docker compose run --rm backup now
git pull && docker compose build && docker compose up -d

Postgres will not read a data directory written by a different major version. Dump, wipe, restore:

docker compose run --rm backup now             # on the OLD version
docker compose down
mv data/postgres data/postgres.old             # keep until you are happy
# edit the image tag in docker-compose.yml and the FROM line in
# docker/backup/Dockerfile to the same new major version
docker compose build backup
docker compose up -d postgres
docker compose run --rm backup restore run <stamp>   # once per database
docker compose up -d

The vector index restores with everything else, so nothing is re-embedded.

Development

bun install
bun test          # 145 tests
bun run check     # typecheck, lint, test

Bun runs TypeScript directly, so there is no build step and the containers run the source. bun run --cwd packages/dashboard preview writes a preview.html with sample data.

How it fits together:

• The indexer is incremental. It fingerprints each page and skips anything unchanged, so a pass over an untouched wiki costs nothing.

• Every service with admin credentials prepares the database at boot, under an advisory lock, so start order does not matter.

• The dashboard is server-rendered HTML with inline SVG charts. No client JavaScript, no chart library, no build step.

Publishing the website. website/index.html deploys to GitHub Pages on every push that touches it. Enable Pages once by hand first: Settings → Pages → Build and deployment → Source: GitHub Actions. This cannot be automated, because creating a Pages site needs a token with administration rights and GITHUB_TOKEN does not have them.

License

Apache-2.0. See LICENSE.