zerochan-mcp

A Python MCP server wrapping the read-only Zerochan anime image board API. Connect it to Claude Desktop, Cursor, or any MCP-compatible AI assistant to browse, search, and inspect one of the web's most comprehensively tagged anime image collections — directly from a conversation.

Built as a sister server to gelbooru-mcp.

✨ Features

Browse the global Zerochan feed — sort by newest or most-favorited, filter by dimensions or dominant color
Search by one or more tags simultaneously using Zerochan's natural Title Case format (Hatsune Miku, not hatsune_miku)
Strict mode — narrow results to entries where a specific tag is the primary subject, cutting group shots and incidental appearances
Full entry details — all tags, full/medium/small image URLs, source, dimensions, favorites, and anime/manga/game associations
Returns results as a clean Markdown table or raw JSON — your choice
Fully Pydantic-validated inputs with enum constraints and custom tag validators
Clear, actionable error messages for rate limits, auth failures, and timeouts

📦 Installation

Prerequisites

Python 3.10+
git

Quick Start

git clone https://github.com/citronlegacy/zerochan-mcp.git
cd zerochan-mcp
chmod +x setup.sh && ./setup.sh

Or without chmod:

bash setup.sh

Manual Install

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

🔑 Authentication

Zerochan requires a valid username in every request's User-Agent header. Unauthenticated requests are blocked.

export ZEROCHAN_USERNAME="YourZerochanUsername"

Your username is included in the User-Agent string as zerochan-mcp - YourUsername, exactly as Zerochan's API requires. The server validates this on every call and returns a clear error message if it is missing — no silent failures.

▶️ Running the Server

# via the venv created by setup.sh:
.venv/bin/python server.py

# or with the venv activated:
source .venv/bin/activate
python server.py

⚙️ Configuration

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "zerochan-mcp": {
      "command": "/absolute/path/to/zerochan-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/zerochan-mcp/server.py"],
      "env": {
        "ZEROCHAN_USERNAME": "YourZerochanUsername"
      }
    }
  }
}

VS Code / Cursor / Other MCP Clients

Configure according to your client's documentation:

Command: /absolute/path/to/zerochan-mcp/.venv/bin/python
Args: /absolute/path/to/zerochan-mcp/server.py
Transport: stdio
Env: ZEROCHAN_USERNAME=YourZerochanUsername

Test with MCP Inspector

npx @modelcontextprotocol/inspector .venv/bin/python server.py

💡 Usage Examples

Browse the latest anime art

"Show me the 10 most recent images on Zerochan."

The LLM calls zerochan_browse with limit: 10, sort: "id" and returns a paginated Markdown table of the newest uploads — IDs, tags, dimensions, and direct links.

Find the all-time most favorited images

"What are the most popular images on Zerochan of all time?"

The LLM calls zerochan_browse with sort: "fav", time_range: "0" and returns the highest-favorited entries globally.

Search for a character

"Find me portrait-mode images of Hatsune Miku."

The LLM calls zerochan_search with tags: ["Hatsune Miku"], dimensions: "portrait". No tag normalization required — Zerochan's Title Case maps almost one-to-one with how people naturally write character names.

Multi-tag search — character + theme

"Show me Rem from Re:Zero with an umbrella."

The LLM calls zerochan_search with tags: ["Rem", "Umbrella"]. Zerochan joins them as /Rem,Umbrella?json internally, returning only images tagged with both simultaneously.

Strict mode — images where a character is the main subject

"I only want images where Hatsune Miku is the actual primary subject, not just tagged."

The LLM calls zerochan_search with tags: ["Hatsune Miku"], strict: true. This filters to entries where Hatsune Miku is the primary tag, removing group shots and background appearances.

Get full metadata for a specific post

"Give me all the details on Zerochan entry 3793685 — tags, source, full image URL."

The LLM calls zerochan_get_entry with entry_id: 3793685 and returns a complete metadata card: every tag, full/medium/small image URLs, source, dimensions, favorites, and associated anime/game/manga categories.

Raw JSON for downstream processing

"Search for Yotsuba images and give me the raw JSON."

The LLM calls zerochan_search with tags: ["Yotsuba"], response_format: "json" and returns the unprocessed Zerochan API payload ready for further processing.

🛠️ Available Tools

Tool	Description	Key Parameters
`zerochan_browse`	Browse the global Zerochan feed	`page`, `limit`, `sort`, `time_range`, `dimensions`, `color`
`zerochan_search`	Search entries by one or more tags	`tags`, `strict`, `page`, `limit`, `sort`, `dimensions`, `color`
`zerochan_get_entry`	Get full metadata for a single entry by ID	`entry_id`

All tools accept response_format: "markdown" (default) or "json".

📖 Tools Reference

`zerochan_browse`

Browse all Zerochan entries with optional filtering and pagination. No tag required — queries the full global feed.

Parameters

Parameter	Type	Required	Default	Description
`page`	int	❌	1	Page number (starts at 1)
`limit`	int	❌	20	Results per page (1–250)
`sort`	enum	❌	`id`	`id` = newest first, `fav` = most favorited
`time_range`	enum	❌	—	`0` = all time, `1` = last 7 000 entries, `2` = last 15 000 entries
`dimensions`	enum	❌	—	`large`, `huge`, `landscape`, `portrait`, `square`
`color`	str	❌	—	Dominant color name, e.g. `blue`, `red`, `pink`
`response_format`	enum	❌	`markdown`	`markdown` or `json`

Example response

### Zerochan Results from `Global Feed`

| ID | Tags | Dimensions | Favorites | Full Image |
|---|---|---|---|---|
| 4666171 | Female, Twin Tails, Flower, Hatsune Miku, Music (+33 more) | 1000×1500 | ? | View |

`zerochan_search`

Search Zerochan entries by one or more tags. Tags use Zerochan's Title Case with spaces format.

Parameters

Parameter	Type	Required	Default	Description
`tags`	list[str]	✅	—	One or more tags, e.g. `["Hatsune Miku"]` or `["Rem", "Umbrella"]`
`strict`	bool	❌	false	Restrict to entries where the first tag is the primary tag (single-tag only)
`page`	int	❌	1	Page number
`limit`	int	❌	20	Results per page (1–250)
`sort`	enum	❌	`id`	`id` = newest, `fav` = most favorited
`dimensions`	enum	❌	—	`large`, `huge`, `landscape`, `portrait`, `square`
`color`	str	❌	—	Dominant color filter
`response_format`	enum	❌	`markdown`	`markdown` or `json`

Tag format: Zerochan uses Title Case with spaces — Hatsune Miku not hatsune_miku. Natural-language character names work verbatim in most cases.

Multi-tag: tags: ["Hatsune Miku", "Flower"] → /Hatsune+Miku,Flower?json

Strict mode: Only works with a single tag. Silently ignored when multiple tags are provided.

`zerochan_get_entry`

Retrieve complete metadata for a single Zerochan post by its numeric ID.

Parameters

Parameter	Type	Required	Default	Description
`entry_id`	int	✅	—	Numeric post ID, e.g. `3793685` (visible in the post URL)
`response_format`	enum	❌	`markdown`	`markdown` or `json`

Example response (markdown)

## Zerochan Entry #3793685

**Primary Tag:** Hatsune Miku
**Dimensions:** 1748 × 2480
**Favorites:** 42
**Source:** https://...
**Tags (28):** Hatsune Miku, VOCALOID, Female, Twin Tails, ...

**Full Image:** https://static.zerochan.net/...
**Medium Preview:** https://static.zerochan.net/...

Response schema (JSON)

{
  "id": 3793685,
  "primary": "Hatsune Miku",
  "tags": ["Hatsune Miku", "VOCALOID", "Female", "..."],
  "width": 1748,
  "height": 2480,
  "fav": 42,
  "source": "https://...",
  "full": "https://static.zerochan.net/...",
  "medium": "https://static.zerochan.net/...",
  "small": "https://static.zerochan.net/...",
  "anime": "VOCALOID",
  "manga": null,
  "game": null
}

🤖 Notes for LLMs

Tag format: Zerochan uses Title Case with spaces — Hatsune Miku, Rem, Attack On Titan. Unlike Gelbooru/Danbooru, natural-language names map directly to Zerochan tags in most cases.
Strict mode: Use it when the user asks specifically for images of a character, not just images featuring them. Only valid with a single tag.
Multi-tag search: Each entry must match all tags. Use for character + theme combos (["Rem", "Rain"], ["Naruto", "Ramen"]).
Pagination: zerochan_browse and zerochan_search return up to 250 results per call. Use page to paginate through up to 100 pages (20 000 entries) per tag.
Rate limit: 60 requests/minute. Avoid tight loops; space calls when paginating deeply.
Entry IDs: Visible in Zerochan URLs (zerochan.net/3793685). Pass them to zerochan_get_entry to resolve full metadata.

⚠️ Known Limitations

Rate limit: 60 requests/minute enforced server-side. Exceeding this may trigger a temporary ban.
Username required: Every request must carry a valid Zerochan username in the User-Agent. The server validates this and returns a clear error if missing.
Strict mode + multi-tag: Strict mode is silently ignored when more than one tag is provided — Zerochan API limitation.
No write access: Zerochan's public API is fully read-only. Uploading, favoriting, and commenting are not supported.
No tag autocomplete: Zerochan does not expose a tag search/autocomplete endpoint in the JSON API. Use the website for tag discovery when needed.

🐛 Troubleshooting

ZEROCHAN_USERNAME is not set

Add it to your client's "env" block, or: export ZEROCHAN_USERNAME="YourUsername"

Error 403 — Access denied

Ensure your Zerochan username is correct and your account is in good standing.
Blank or missing User-Agent strings are rejected by Zerochan.

Error 429 — Rate limit

Wait 60 seconds and retry. Avoid paginating in rapid loops.

Error 404 — Not found

The tag or entry ID does not exist on Zerochan. Check spelling; entry IDs come from post URLs.

Strict mode returns fewer results than expected

By design — strict mode returns only entries where the tag is the primary classification. Use non-strict for broader results.

🤝 Contributing

Pull requests are welcome! If you find an API edge case not handled, a tag format inconsistency, or want to add a new filter, open an issue or PR.

Development Setup

git clone https://github.com/citronlegacy/zerochan-mcp.git
cd zerochan-mcp
bash setup.sh
source .venv/bin/activate

📄 License

MIT License — see LICENSE for details.

🔗 Links

🌐 Zerochan
🔧 MCP documentation
🗂️ MCP Registry
🔍 Glama MCP Directory
🎨 gelbooru-mcp — sister MCP server
🐛 Bug Reports
💡 Discussions

Relation to MultiBoru MCP

This server is one piece of a planned MultiBoru federated image board MCP that will aggregate Gelbooru, Danbooru, and Zerochan queries in parallel with cross-site tag normalization.

Site	Max Tags	Tag Format	Auth
Gelbooru	Many	`snake_case`	Optional API key
Danbooru	2 (free) / 6 (Gold)	`snake_case`	Optional
Zerochan	Many	`Title Case`	Username in User-Agent

ZeroChan MCP

zerochan-mcp

✨ Features

📦 Installation

Prerequisites

Quick Start

Manual Install

🔑 Authentication

▶️ Running the Server

⚙️ Configuration

Claude Desktop

VS Code / Cursor / Other MCP Clients

Test with MCP Inspector

💡 Usage Examples

Browse the latest anime art

Find the all-time most favorited images

Search for a character

Multi-tag search — character + theme

Strict mode — images where a character is the main subject

Get full metadata for a specific post

Raw JSON for downstream processing

🛠️ Available Tools

📖 Tools Reference

`zerochan_browse`

`zerochan_search`

`zerochan_get_entry`

🤖 Notes for LLMs

⚠️ Known Limitations

🐛 Troubleshooting

🤝 Contributing

Development Setup

📄 License

🔗 Links

Relation to MultiBoru MCP

Reviews