Gelbooru Mcp
@citronlegacy
A Python MCP server that wraps the Gelbooru API. Connect it to any MCP-compatible client (Claude Desktop, Cursor, etc.) to search posts, look up tags, and generate Stable Diffusion prompts from real character appearance data — all directly from your AI assistant.
Overview
What is Gelbooru Mcp?
A Python MCP server that wraps the Gelbooru API. Connect it to any MCP-compatible client (Claude Desktop, Cursor, etc.) to search posts, look up tags, and generate Stable Diffusion prompts from real character appearance data — all directly from your AI assistant.
How to use Gelbooru Mcp?
Clone the repository, run install.sh (or install mcp manually with pip), then set the optional environment variables GELBOORU_API_KEY and GELBOORU_USER_ID. Start the server with python gelbooru_mcp.py and configure your MCP client (e.g., Claude Desktop) to run the script via the stdio transport.
Key features of Gelbooru Mcp
- Stable Diffusion Prompt Generation – Build accurate SD prompts from tag frequency data.
- Appearance Breakdown – Separate eye, hair, and clothing tags with frequency counts.
- Advanced Post Search – Filter by tags, score, resolution, rating, uploader, and more.
- Full Tag Syntax – Supports AND, OR, wildcards, exclusion, meta-tags, and sorting.
- Community Tools – Search users, get post comments, and list deleted posts.
- Smart Caching – Results cached for 24 hours to avoid repeated API calls.
Use cases of Gelbooru Mcp
- Generate a Stable Diffusion prompt for a character by analyzing their most-tagged posts.
- Find high-quality wallpaper images using score, width, and tag filters.
- Check how many posts a specific tag has and discover related tags.
- Retrieve comments on a given post or track recently deleted content.
FAQ from Gelbooru Mcp
Do I need a Gelbooru API key?
API credentials are optional but strongly recommended. Without them, requests are throttled and limited to 2 tags per query. Patreon supporters of Gelbooru receive unlimited requests.
What are the runtime requirements?
Python 3.10+ and the mcp package. The server uses the stdio transport and does not require a web server.
How are Stable Diffusion prompts generated?
The server fetches the most-tagged rating:general solo posts for a character, analyzes tag frequency across eye, hair, and other categories, then assembles a ready-to-paste prompt string. Results are cached for 24 hours by default.
What tag format does Gelbooru use?
Gelbooru uses character_(series) format with underscores (e.g., misty_(pokemon)). Always convert natural language names to this format before using the tools. Use search_tags with name_pattern if unsure.
