xkcd Comic Suggester MCP server

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)

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.

• Data: title + mouseover alt from the official API, plus the community

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).

• Embeddings: fastembed (ONNX) with BAAI/bge-small-en-v1.5 — local, free,

few thousand comics.

• Search: a normalized numpy matrix + dot product. No vector DB needed for a

cutoff alone can't judge relevance. minscore (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 findxkcd tool.

• Restraint: because xkcd has a comic for almost everything, a similarity

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):

For Claude to suggest comics on its own, also add the instruction from Make Claude suggest comics proactively to your Profile preferences.

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.

Notes

no secrets). Don't reuse this pattern for anything sensitive without OAuth.

• The server is public and unauthenticated — fine here (read-only comic search,

pushes to main auto-redeploy.

• Hosted from this repo via the Dockerfile and render.yaml;

handy on a 512 MB instance:

• GET /healthz reports liveness, whether the index is loaded, and current RSS —

curl https://xkcdai.onrender.com/healthz

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:

Shortened. The full README is on GitHub.