Skip to main content
Glama

xkcd-mcp

Comics for your LLM via the official xkcd JSON API - no scraping.

📖 Installation Guide — quick start, manual setup, and troubleshooting


The part humans read first

xkcd-mcp Comics for your LLM. Official JSON API (/info.0.json), unofficial amount of stick-figure drama.

You get a small Vite dashboard with a comic-panel hero: stick people, a speech bubble that says MCP, explain this, and a box labeled JSON that definitely understands your feelings. The README cant draw SVG, so imagine it badlysame energy as the web app.

Alt text (this repo): A README receives a pull request titled make it whimsical. The CI passes. The narrator questions whether that was ever in scope.

Alt text (the app): A tiny server labeled JSON gets enthusiastic waves while someone negotiates with the universe. Hover tooltips not included; thats what the comic alt is for.

No scraping. No Explainxkcd body fetch. Were not here to parse HTML like its 2003.

Repo: github.com/sandraschi/xkcd-mcp


Quick Start

git clone https://github.com/sandraschi/xkcd-mcp
cd xkcd-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

Related MCP server: xkcdai

Technical details

What it is

  • MCP server + HTTP API exposing xkcd metadata and image URLs via the official API and explainxkcd semantic search.

  • Web UI calls POST /api/comic with the same operations as the tool (latest, random, by_number, search).

MCP tools

Tool

Description

Arguments

xkcd_latest

Fetch the most recent comic.

None

xkcd_get

Fetch a specific comic by number.

comic_number (int)

xkcd_random

Fetch a random surprise comic.

None

xkcd_search

Search comics by topic (aliens, climate).

query (str)

xkcd_help

Display usage guide and system info.

None

Prefab UI (Rich In-Chat Comics)

When installed with the apps extra and used in a compatible client (Claude Desktop, Antigravity), these tools render a rich PrefabApp card containing:

  • The comic image (high-resolution, base64-encoded).

  • The comic title and number.

  • The alt text directly below the image for context.

  • A link to the original xkcd page.

This provides a seamless, visual way to consume comics without leaving the chat interface.

Install

To get started, clone the repository and sync dependencies:

git clone https://github.com/sandraschi/xkcd-mcp.git
Set-Location xkcd-mcp

# Sync all dependencies (v0.2.0)
uv sync

# RECOMMENDED: FastMCP 3.2 Prefab UI support (rich in-chat comics)
uv sync --extra apps

MCP Configuration (Claude / Antigravity)

Add the following to your mcp_config.json (Antigravity) or claude_desktop_config.json (Claude):

{
  "mcpServers": {
    "xkcd": {
      "command": "uv",
      "args": ["--directory", "D:/Dev/repos/xkcd-mcp", "run", "xkcd-mcp"],
      "env": {
        "XKCD_PREFAB_APPS": "1"
      }
    }
  }
}
TIP

Ensure theargs path matches your actual disk location. Using uv run is the most reliable way to ensure the correct environment and apps extra are loaded.


Run Manual Start

uv run xkcd-mcp --serve

Item

Value

HTTP

http://127.0.0.1:10778 /health, /docs

MCP

http://127.0.0.1:10778/mcp

Env

XKCD_MCP_HOST, XKCD_MCP_PORT (default 10778), XKCD_MCP_HTTP_PATH (default /mcp)

Run web UI (SPA)

.\web_sota\start.ps1

Or double-click web_sota\start.bat (launches the same script).

http://127.0.0.1:10779/ (same repo root as install)

Fleet docs (LLM index)

  • llms.txt short index; llms-full.txt tools, env, ports, troubleshooting.

🛡️ Industrial Quality Stack

This project adheres to SOTA 14.1 industrial standards for high-fidelity agentic orchestration:

  • Python (Core): Ruff for linting and formatting. Zero-tolerance for print statements in core handlers (T201).

  • Webapp (UI): Biome for sub-millisecond linting. Strict noConsoleLog enforcement.

  • Protocol Compliance: Hardened stdout/stderr isolation to ensure crash-resistant JSON-RPC communication.

  • Automation: Justfile recipes for all fleet operations (just lint, just fix, just dev).

  • Security: Automated audits via bandit and safety.

License

MIT

Available Tools

6 tools
show_comic_prefab_cardA

Show a rich prefab card for an xkcd comic. Fetches random if no number given.

This tool renders an interactive UI in the chat. Prefer it over text output when displaying data from other xkcd-mcp tools.

Inputs: comic_number.

xkcd_getA

Fetch a specific xkcd comic by its number.

Inputs: comic_number (required).

xkcd_helpA

Get help and usage information for xkcd-mcp tools and configuration.

Inputs: no named parameters.

xkcd_latestA

Fetch the latest comic from xkcd.com.

Inputs: no named parameters.

xkcd_randomA

Fetch a random comic from the entire xkcd collection.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have distinct purposes: get by number, latest, random, search, help. However, 'show_comic_prefab_card' can fetch random if no number given, overlapping with 'xkcd_random', which could cause confusion for an agent.

    Naming Consistency3/5

    Five tools use the 'xkcd_' prefix (underscore style), but 'show_comic_prefab_card' breaks the pattern with a different verb and style, mixing conventions. Considering the small set, the inconsistency is noticeable.

    Tool Count5/5

    With 6 tools covering retrieval, search, help, and UI rendering, the count is well-scoped for a domain-specific xkcd server. Each tool serves a clear purpose without excessive overlap.

    Completeness4/5

    Core operations are covered: get by number, latest, random, search. A minor gap is the lack of a 'list all' or pagination tool, but search compensates for topic-based discovery. Help tool adds guidance.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that finds relevant xkcd comics during conversation by semantically matching the context to comic titles, alt text, and transcripts.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that extracts rich metadata (title, description, duration, chapters, subtitles, statistics, etc.) from media URLs across thousands of sites using yt-dlp, and also provides transcript fetching and search capabilities.
      3
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides web search scraping from DuckDuckGo (with Mojeek fallback) and URL content fetching as markdown/text or raw HTML.
      1
      ISC