README.md

---
title: Xkcd Mcp Server
emoji: 📊
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: mit
short_description: XKCD Remote MCP Server
---

# XKCD MCP Server

A Model Context Protocol (MCP) server for fetching and searching XKCD comics, built with Gradio.

## Features

- **Get XKCD Comic**: Fetch specific comics by ID or get the latest comic
- **Search Comics**: Search through recent comics by title, alt text, and transcript

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Run the server:
```bash
python app.py
```

## MCP Tools Available

### `get_xkcd_comic`
Fetch XKCD comic information by ID or get the latest comic.

**Parameters:**
- `comic_id` (str): Comic ID number (leave empty for latest comic)

**Returns:** JSON string with comic data including title, alt text, image URL, and metadata.

### `search_xkcd_transcript`
Search for XKCD comics by searching their transcripts and titles.

**Parameters:**
- `search_term` (str): Term to search for in comic transcripts and titles

**Returns:** JSON string with matching comics information.

## Deployment to Hugging Face Spaces

1. Create a new Space on Hugging Face
2. Upload `app.py` and `requirements.txt`
3. Set the Space to use Gradio SDK
4. Configure your MCP client to connect to the Space URL

## Usage with MCP Clients

Configure your MCP client (e.g., Claude Desktop) to connect to this server:

```json
{
  "servers": {
    "xkcd": {
      "command": "python",
      "args": ["app.py"]
    }
  }
}
```

Or use the Hugging Face Spaces URL if deployed online.