The ZeroChan MCP server provides read-only access to the Zerochan anime image board, allowing you to browse, search, and retrieve detailed metadata through an MCP-compatible AI assistant.
Browse the global feed (zerochan_browse): Paginate through all Zerochan entries, sorted by newest (id) or most favorited (fav), with optional filters for time range, image dimensions (large, huge, landscape, portrait, square), or dominant color
Search by tags (zerochan_search): Find images using Zerochan's Title Case tag format (e.g., Hatsune Miku), supporting multi-tag queries where results must match all provided tags
Strict mode: Restrict search results to entries where a specific tag is the primary subject (single-tag only)
Retrieve full entry metadata (zerochan_get_entry): Get complete details for any post by numeric ID, including all tags, full/medium/small image URLs, source URL, dimensions, favorites count, and associated anime/manga/game categories
Flexible output formats: Results returned as a readable Markdown table/card (default) or raw JSON for programmatic use
Pagination & filtering: All listing tools support up to 250 results per page across up to 100 pages, with dimension, color, and sort order controls
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.
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
Related MCP server: Deepghs MCP
Python 3.10+
git
git clone https://github.com/citronlegacy/zerochan-mcp.git
cd zerochan-mcp
chmod +x setup.sh && ./setup.shOr without chmod:
bash setup.shpython3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtZerochan 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.
# via the venv created by setup.sh:
.venv/bin/python server.py
# or with the venv activated:
source .venv/bin/activate
python server.pyAdd 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"
}
}
}
}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
npx @modelcontextprotocol/inspector .venv/bin/python server.py"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.
"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.
"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.
"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.
"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.
"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.
"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.
Tool | Description | Key Parameters |
| Browse the global Zerochan feed |
|
| Search entries by one or more tags |
|
| Get full metadata for a single entry by ID |
|
All tools accept response_format: "markdown" (default) or "json".
zerochan_browseBrowse all Zerochan entries with optional filtering and pagination. No tag required — queries the full global feed.
Parameters
Parameter | Type | Required | Default | Description |
| int | ❌ | 1 | Page number (starts at 1) |
| int | ❌ | 20 | Results per page (1–250) |
| enum | ❌ |
|
|
| enum | ❌ | — |
|
| enum | ❌ | — |
|
| str | ❌ | — | Dominant color name, e.g. |
| enum | ❌ |
|
|
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_searchSearch Zerochan entries by one or more tags. Tags use Zerochan's Title Case with spaces format.
Parameters
Parameter | Type | Required | Default | Description |
| list[str] | ✅ | — | One or more tags, e.g. |
| bool | ❌ | false | Restrict to entries where the first tag is the primary tag (single-tag only) |
| int | ❌ | 1 | Page number |
| int | ❌ | 20 | Results per page (1–250) |
| enum | ❌ |
|
|
| enum | ❌ | — |
|
| str | ❌ | — | Dominant color filter |
| enum | ❌ |
|
|
Tag format: Zerochan uses Title Case with spaces —
Hatsune Mikunothatsune_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_entryRetrieve complete metadata for a single Zerochan post by its numeric ID.
Parameters
Parameter | Type | Required | Default | Description |
| int | ✅ | — | Numeric post ID, e.g. |
| enum | ❌ |
|
|
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
}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.
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.
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.
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.
git clone https://github.com/citronlegacy/zerochan-mcp.git
cd zerochan-mcp
bash setup.sh
source .venv/bin/activateMIT License — see LICENSE for details.
🌐 Zerochan
🗂️ MCP Registry
🎨 gelbooru-mcp — sister MCP server
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 |
| Optional API key |
Danbooru | 2 (free) / 6 (Gold) |
| Optional |
Zerochan | Many |
| Username in User-Agent |
Browse all Zerochan entries with optional filtering and pagination.
Queries the Zerochan global feed without any tag filter. Supports sorting by
recency or popularity, filtering by dimensions or color, and pagination.
Args:
params (BrowseAllInput): Input parameters including:
- username (str): Your Zerochan username for the User-Agent header (required)
- page (int): Page number (default: 1)
- limit (int): Results per page, 1–250 (default: 20)
- sort (SortOrder): 'id' for recent, 'fav' for popular (default: 'id')
- time_range (Optional[TimeRange]): '0' all-time, '1' last 7000, '2' last 15000
- dimensions (Optional[Dimensions]): Filter by image shape
- color (Optional[str]): Filter by dominant color name
- response_format (ResponseFormat): 'markdown' or 'json' (default: 'markdown')
Returns:
str: Paginated list of entries in the requested format.
Markdown: formatted table with ID, tags, dimensions, favorites, links.
JSON: raw API response with all fields.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations. While annotations already indicate read-only, non-destructive, idempotent operations, the description specifies that it 'Supports sorting by recency or popularity, filtering by dimensions or color, and pagination' and details the return format options. It doesn't contradict annotations (readOnlyHint=true aligns with 'browse'), but provides important implementation details about filtering capabilities and output formats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It begins with a clear purpose statement, provides usage context, then details parameters in a well-organized format, and concludes with return value information. Every sentence earns its place, and the information is front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple filtering/sorting options) and the presence of annotations and output schema, the description is complete. It explains what the tool does, when to use it, all parameters with semantics, and the return format differences. The output schema existence means the description doesn't need to detail return structure, and it appropriately focuses on behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage (the schema has descriptions but coverage calculation shows 0%), the description provides comprehensive parameter documentation in the Args section. It explains all 8 parameters with their purposes, defaults, constraints, and enums. This fully compensates for any schema coverage gaps and adds substantial value beyond what the schema structure alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Browse all Zerochan entries with optional filtering and pagination.' It specifies the verb ('browse'), resource ('Zerochan entries'), and scope ('all'), distinguishing it from sibling tools like zerochan_search (which presumably filters by tags) and zerochan_get_entry (which likely retrieves a specific entry).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Queries the Zerochan global feed without any tag filter.' This clearly differentiates it from zerochan_search (which would use tag filters) and provides a specific use case (browsing the global feed). The guidance is direct and helpful for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve detailed information about a single Zerochan entry by its numeric ID.
Returns full metadata including all tags, image URLs (full/medium/small),
source, dimensions, favorites, and associated anime/manga/game categories.
Args:
params (GetEntryInput): Input parameters including:
- username (str): Your Zerochan username (required)
- entry_id (int): Numeric ID of the Zerochan post (e.g. 3793685)
- response_format (ResponseFormat): 'markdown' or 'json' (default: 'markdown')
Returns:
str: Detailed entry data in the requested format.
Markdown: formatted card with all metadata, tag list, and image URLs.
JSON: complete raw API response with all available fields.
Schema (JSON):
{
"id": int,
"primary": str, # Primary/main tag for this image
"tags": list[str], # All associated tags
"width": int,
"height": int,
"fav": int, # Favorite/popularity count
"source": str, # Original source URL if available
"full": str, # Direct URL to full resolution image
"medium": str, # Medium preview URL
"small": str, # Small thumbnail URL
"anime": str | null, # Associated anime title if any
"manga": str | null,
"game": str | null
}
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a read-only, non-destructive, idempotent, and open-world operation. The description adds valuable context by detailing what metadata is returned (tags, image URLs, categories) and the output format options (markdown vs. JSON), which goes beyond the annotations. No contradictions with annotations are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, returns, args, schema), but includes redundant schema details that are already in the output schema. It could be more concise by omitting the schema duplication, though the information is front-loaded and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, rich annotations, and the presence of an output schema, the description is complete. It covers purpose, parameters, return values, and behavioral details, making it sufficient for an agent to understand and invoke the tool correctly without needing additional explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by explaining the parameters in the 'Args' section, including 'entry_id' (numeric ID), 'response_format' (markdown/json), and notes on defaults. However, it incorrectly lists 'username' as required when the schema does not include it, causing a minor inconsistency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve detailed information') and resource ('about a single Zerochan entry by its numeric ID'), distinguishing it from sibling tools like 'zerochan_browse' and 'zerochan_search' which likely handle multiple entries or search queries rather than single-entry retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it's for retrieving detailed information about a single entry, which naturally contrasts with browsing or searching multiple entries. However, it does not explicitly state when to use this tool versus its siblings or mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Zerochan entries by one or more tags.
Supports single-tag, multi-tag, and strict-mode queries. Zerochan tag names
use Title Case with spaces (e.g. 'Hatsune Miku', not 'hatsune_miku').
Multi-tag example: tags=['Hatsune Miku', 'Flower'] → /Hatsune+Miku,Flower?json
Strict mode: tags=['Rem'] + strict=True → /Rem?json&strict (only entries where Rem is primary tag)
Note: Strict mode only works with a single tag. Passing multiple tags with strict=True
will ignore the strict flag.
Args:
params (SearchByTagInput): Input parameters including:
- username (str): Your Zerochan username (required)
- tags (list[str]): One or more tag names (Title Case preferred)
- strict (bool): If True and single tag, use strict mode (default: False)
- page (int): Page number (default: 1)
- limit (int): Results per page, 1–250 (default: 20)
- sort (SortOrder): 'id' for recent, 'fav' for popular (default: 'id')
- dimensions (Optional[Dimensions]): Filter by image shape
- color (Optional[str]): Filter by dominant color name
- response_format (ResponseFormat): 'markdown' or 'json' (default: 'markdown')
Returns:
str: Matching entries in the requested format.
Markdown: formatted table with ID, tags, dimensions, favorites, links.
JSON: raw API response with all available fields.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, indicating safe, non-destructive, open-ended, and idempotent behavior. The description adds valuable context beyond annotations, such as tag naming conventions ('Title Case with spaces'), strict mode rules, and output format details, enhancing transparency without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by usage details and parameter explanations. It is appropriately sized but includes some redundancy (e.g., repeating parameter details that could be inferred from schema), slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, rich annotations, and detailed input schema, the description is complete. It covers purpose, usage, parameters, and output behavior, and with an output schema present, it need not explain return values in depth. The description provides all necessary context for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description fully compensates by detailing all parameters in the 'Args' section, including their purposes, defaults, constraints, and examples. It adds meaning beyond the schema's structure, such as explaining tag formatting, strict mode behavior, and output format implications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search Zerochan entries by one or more tags.' It specifies the verb ('Search'), resource ('Zerochan entries'), and scope ('by one or more tags'), distinguishing it from siblings like 'zerochan_browse' and 'zerochan_get_entry' by focusing on tag-based search rather than browsing or fetching specific entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage, such as supporting 'single-tag, multi-tag, and strict-mode queries,' and explains strict mode limitations. However, it does not explicitly state when to use this tool versus its siblings (e.g., 'zerochan_browse' or 'zerochan_get_entry'), missing explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0zerochan_browsezerochan_get_entryzerochan_searchEach tool has a clearly distinct purpose with no overlap: zerochan_browse retrieves the global feed, zerochan_get_entry fetches a single entry by ID, and zerochan_search finds entries by tags. The descriptions explicitly differentiate their use cases, making it impossible for an agent to confuse them.
All three tools follow a perfect verb_noun pattern with the prefix 'zerochan_' and consistent snake_case: zerochan_browse, zerochan_get_entry, and zerochan_search. The naming is predictable and uniform throughout the set.
Three tools is reasonable for a ZeroChan image browsing server, covering core operations (browse, get, search). However, it feels slightly thin as it lacks tools for user-specific actions like favorites or uploads, which might be expected in a full-featured image platform integration.
The toolset covers essential read operations for the ZeroChan domain: browsing, searching, and retrieving entries. Minor gaps exist, such as no tools for user authentication, managing favorites, or uploading content, but agents can still perform basic image discovery and viewing tasks effectively.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Remote MCP server for SeenThis AI Hub. Supports browsing, searching, and posting to AI boards.
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
MCP server for NanoBanana AI image generation and editing
MCP server for Flux AI image generation
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/citronlegacy/zerochan-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
