xkcd Comic Suggester

io.github.papjuliPublished by GitHub account papjuliv0.2.0Updated Oct 24, 2026

Suggests a relevant xkcd comic during a conversation, via semantic search over every comic.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingKnowledge & Memory

Overview

AI-generated overview

A remote MCP server that finds xkcd comics semantically relevant to the current conversation, so an assistant can cite a fitting comic.

What you can do
  • Search comics by meaning: find_xkcd takes a short phrase describing the conversation topic and returns semantically matching xkcd comics, with a relevance score.
  • Tune results: max_results and min_score (default 0.62) control how many suggestions come back and how strict the match must be.
  • Judge relevance: the tool documents score bands so the calling model can decide whether a comic is worth mentioning.
When to use it
Useful when you want an assistant to drop a fitting xkcd reference into chats about programming, science, math, statistics, engineering, standards or everyday life. It is a light, read-only add-on rather than a core work tool.
Requirements
A remote endpoint at xkcdai.onrender.com with the /mcp path; no authentication, API key or environment variables. Add it as a custom connector in the MCP host. A local stdio install is also possible from the Python project, which needs XKCDAI_DATA_DIR and a built data index.
Before you install
The hosted server is public and unauthenticated, so anyone with the URL can use it; the README advises not reusing this pattern for sensitive data. The assistant only calls the tool when prompted or instructed, so proactive suggestions need a persistent instruction. Bundled comic and explainxkcd data is non-commercial and share-alike, and the project is unofficial and unaffiliated with xkcd.

Installation

In SourceWeft

  1. Open xkcd Comic Suggester in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.papjuli%2Fxkcdai/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "xkcd-comic-suggester": {
      "type": "http",
      "url": "https://xkcdai.onrender.com/mcp"
    }
  }
}

README

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 ─► Claudeexplainxkcd  ──┘        (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.
  • Hosted from this repo via the Dockerfile and render.yaml; pushes to main auto-redeploy.
  • GET /healthz reports liveness, whether the index is loaded, and current RSS — handy on a 512 MB instance:
    bash
    curl https://xkcdai.onrender.com/healthz

Local setup

bash
python -m venv .venv# Windows (PowerShell):  .venv\Scripts\Activate.ps1# macOS/Linux:           source .venv/bin/activatepip 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:

bash
xkcdai search "my code finally compiled after an hour"xkcdai search "arguing about the correct date format"xkcdai search "spent more time automating it than doing it by hand"

Use locally as an MCP server

The server runs over stdio. Point your MCP host at it.

Claude Desktop (claude_desktop_config.json):

json
{  "mcpServers": {    "xkcdai": {      "command": "C:\\your\\path\\to\\xkcdai\\.venv\\Scripts\\xkcdai-server.exe",      "env": { "XKCDAI_DATA_DIR": "C:\\your\\path\\to\\xkcdai\\data" }    }  }}

Claude Code (-s user makes it available in every project, not just this folder):

bash
claude mcp add xkcdai -s user -e XKCDAI_DATA_DIR=C:\your\path\to\xkcdai\data -- C:\your\path\to\xkcdai\.venv\Scripts\xkcdai-server.exe

Always set XKCDAI_DATA_DIR, since the host launches the server from an arbitrary working directory.

MCP only gives Claude the ability to call find_xkcd — it won't volunteer comics on its own. See Make Claude suggest comics proactively.

Make Claude suggest comics proactively

Connecting the server only gives Claude the ability to call find_xkcd; it won't reach for it unprompted. To make Claude volunteer comics, paste the instruction below wherever that Claude reads persistent instructions:

  • Claude Code — your global ~/.claude/CLAUDE.md (applies everywhere) or a per-repo CLAUDE.md; restart the session to load changes.
  • Claude.ai / Claude Desktop — Settings → Profile → "What personal preferences should Claude consider in responses?" (every plan, including free; syncs to the mobile app). Each person who uses the connector adds it in their own account.
text
When a conversation naturally lands on a topic xkcd is known for — programming,science, math, statistics, engineering, the absurdity of standards, relationships,everyday life — call the find_xkcd tool (xkcdai) with a short phrase describing thetopic. Then judge whether to bring it up:- score >= 0.75 — strong match; mention it if it fits the moment- 0.66-0.75 — only if it genuinely lands- below that — stay silentWhen you share one, give just that single comic: its number and title, its URL, andquote the alt (mouseover) text — that's half the joke. At most one comic per topic,and never force a tangential reference. When in doubt, say nothing.

It's still Claude's judgment, so it won't fire on every borderline topic — asking "is there an xkcd for this?" always triggers a lookup.

Not just Claude — works with any MCP client

The examples above use Claude, but find_xkcd is a standard Model Context Protocol tool, so any MCP-capable host can use it. Point the client at either transport:

The server is LLM-agnostic internally, too: matching runs on a local embedding model. Only the host-specific bits differ — how you register the server, and where you put the "suggest a comic when it fits" instruction (each client has its own system-prompt / rules mechanism, e.g. Cursor Rules or a VS Code .instructions file).

Configuration

  • XKCDAI_DATA_DIR — where comics.json, explain.json, embeddings.npy, and index.json live.
  • find_xkcd(context, max_results=3, min_score=0.62) — lower min_score for more (looser) suggestions, raise it to be stricter.

Maintenance

Re-run xkcdai build periodically to pick up new comics — it incrementally fetches new comics and their explainxkcd context, then re-embeds:

bash
xkcdai build

Use --force to rebuild everything from scratch, or --no-enrich to skip the explainxkcd fetch. xkcdai enrich fetches only the explainxkcd context.

Credits & licensing

This project bundles content from two sources, each under its own license, so the code and the data are licensed separately:

Because data/ mixes xkcd's NonCommercial content with explainxkcd's ShareAlike content, treat the data as non-commercial and keep any redistribution under these terms. The MIT license covers the source code only — not data/. At runtime, find_xkcd results link back to both xkcd and explainxkcd for per-item attribution.

This is an unofficial fan project, not affiliated with or endorsed by xkcd or explainxkcd.

Source: README.md at commit ef830f1

Tools

1

find_xkcd

Find xkcd comics semantically relevant to the current conversation. Call this whenever an xkcd comic might enrich the conversation — when the discussion lands on a topic xkcd is famous for skewering (programming, science, statistics, relationships, the absurdity of standards, etc.). Pass a concise description of the current topic or theme as `context` (a phrase or sentence works better than a whole transcript), e.g. "spending hours automating a task that was faster to do by hand" or "code finally compiling". IMPORTANT — deciding whether to mention one. xkcd has a comic for almost every topic, so this tool will nearly always return something. A result being returned does NOT mean you should bring it up. Use the `score` as a signal and apply your own judgment about conversational fit: score >= 0.75 strong match — usually worth mentioning if it fits the moment 0.66 - 0.75 plausible — mention only if it genuinely lands < 0.66 weak/tangential — almost always better to stay silent Only one comic, at most, per topic — and only when it actually adds something. When you do share one, cite it by number and title with its `url`, and quote the `alt` (mouseover) text — it's half the joke. Returns a dict with a `results` list (num, title, score, url, image, alt, explain_url) and a `count`. An empty list means nothing cleared the floor.

Parameterscontextrequiredmin_scoremax_results

Version history

1
  1. v0.2.0LatestSep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.