xkcdai

An MCP server that surfaces the right xkcd comic during a conversation, if one is relevant.

Live connector: https://xkcdai.onrender.com/mcp — add it in claude.ai → Settings → Connectors. See Use the deployed MCP server.

It builds a semantic index over every xkcd comic (title + mouseover text + transcript) using on-device embeddings, then exposes a single find_xkcd tool. A Claude conversation can call it whenever the topic feels xkcd-shaped; a relevance threshold means weak matches return nothing, so it stays quiet instead of forcing a tenuous reference.

The fetched transcripts, explanations, and the embeddings are currently committed in this repo, under data/.

How it works

xkcd JSON API ─┐
               ├─► comics.json + explain.json ─► embeddings.npy ─► find_xkcd ─► Claude
explainxkcd  ──┘        (cache)                    (bge-small)     (cosine)    (mentions it
 (transcripts +                                                                 if it fits)
  explanations)

• Data: title + mouseover alt from the official API, plus the community transcript and explanation from explainxkcd.com. The explainxkcd context is essential: the official API dropped transcripts around comic ~1675, so without it the most-shared modern comics (e.g. #2347 Dependency) are unmatchable — their joke text lives only inside the image.
• Embeddings: fastembed (ONNX) with BAAI/bge-small-en-v1.5 — local, free, offline after first download, no PyTorch. Swap the model in src/xkcdai/embed.py (e.g. BAAI/bge-base-en-v1.5 for marginally better ranking at ~3× the size).
• Search: a normalized numpy matrix + dot product. No vector DB needed for a few thousand comics.
• Restraint: because xkcd has a comic for almost everything, a similarity cutoff alone can't judge relevance. min_score (default 0.62) is just a coarse floor; the real "should I bring this up?" decision is made by the calling model, guided by the score bands documented on the find_xkcd tool.

Use the deployed MCP server (as custom connector)

The server is deployed at https://xkcdai.onrender.com on Render. Add it as a Claude custom connector to use it in the Claude web and mobile apps (note: the Free plan only allows one custom connector). Anyone can add the same URL in their own account.

In claude.ai (web — do this once; it then syncs to the mobile app):

1. Settings → Connectors → Add custom connector.
2. Paste the connector URL, including the /mcp path: https://xkcdai.onrender.com/mcp
3. Leave OAuth blank (this server needs no auth) and click Add.
4. The connector's find_xkcd tool is now available in chats, on desktop and phone. For Claude to suggest comics on its own, also add the instruction from Make Claude suggest comics proactively to your Profile preferences.

Notes

• The server is public and unauthenticated — fine here (read-only comic search, no secrets). Don't reuse this pattern for anything sensitive without OAuth.
• A free Render instance sleeps when idle, so the first request after a nap is slow (cold start + model load), then snappy.
• Hosted from this repo via the Dockerfile and render.yaml; pushes to main auto-redeploy.

Local setup

python -m venv .venv
# Windows (PowerShell):  .venv\Scripts\Activate.ps1
# macOS/Linux:           source .venv/bin/activate
pip install -e .

# Fetch comics + their explainxkcd context, then embed (downloads the model once).
# First run ~10 min; re-running later only fetches what's new.
xkcdai build

Add --no-enrich to skip the explainxkcd fetch (faster/offline, weaker matches).

Test it from the command line:

xkcdai search "my code finally compiled after an hour"
xkcdai search "ar

... [View full README on GitHub](https://github.com/papjuli/xkcdai#readme)