xkcd-mcp
This server lets you fetch, search, and display xkcd comics via the official JSON API and explainxkcd semantic search.
Fetch the latest xkcd comic.
Fetch a specific comic by number.
Fetch a random comic from the full collection.
Search comics by topic (e.g., aliens, global warming).
Show a rich prefab comic card with image, title, number, alt text, and original link; defaults to random if no number is given.
Get help and usage information for the xkcd-mcp tools and configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xkcd-mcp get the latest xkcd comic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
justThis 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/comicwith the same operations as the tool (latest,random,by_number,search).
MCP tools
Tool | Description | Arguments |
| Fetch the most recent comic. | None |
| Fetch a specific comic by number. |
|
| Fetch a random surprise comic. | None |
| Search comics by topic (aliens, climate). |
|
| 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 appsMCP 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"
}
}
}
}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 --serveItem | Value |
HTTP |
|
MCP |
|
Env |
|
Run web UI (SPA)
.\web_sota\start.ps1Or 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.txtshort index;llms-full.txttools, 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
printstatements in core handlers (T201).Webapp (UI): Biome for sub-millisecond linting. Strict
noConsoleLogenforcement.Protocol Compliance: Hardened
stdout/stderrisolation to ensure crash-resistant JSON-RPC communication.Automation: Justfile recipes for all fleet operations (
just lint,just fix,just dev).Security: Automated audits via
banditandsafety.
License
MIT
Available Tools
6 toolsshow_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.
xkcd_searchB
Search for xkcd comics by topic (e.g., 'aliens', 'global warming'). Uses explainxkcd semantic indexing to find relevant comic numbers.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
An MCP server that provides congressional transcripts
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- AlicenseAqualityAmaintenanceAn MCP server implementation that integrates the SearxNG API, providing web search capabilities.214,935 npm1,365MIT
- AlicenseAqualityDmaintenanceAn MCP server that finds relevant xkcd comics during conversation by semantically matching the context to comic titles, alt text, and transcripts.1MIT
- AlicenseAqualityCmaintenanceAn 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.31MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that provides web search scraping from DuckDuckGo (with Mojeek fallback) and URL content fetching as markdown/text or raw HTML.1ISC