Gelbooru Mcp

Name: Gelbooru Mcp
Author: citronlegacy

@citronlegacy

About 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.

#anime #mcp #booru #gelbooru #prompt-engineering #stable-diffusion #prompt-generator #mcp-server

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "gelbooru-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "/absolute/path/to/gelbooru_mcp.py"
      ],
      "env": {
        "GELBOORU_API_KEY": "your_api_key",
        "GELBOORU_USER_ID": "your_user_id"
      }
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Gelbooru Mcp?

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.