Gelbooru MCP Server

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.

✨ Features

🎨 **Stable Diffusion Prompt Generation**

• Character Prompts: Auto-generate accurate SD prompts from real Gelbooru tag frequency data
• Appearance Breakdown: Separate eye, hair, and clothing/accessory tag categories
• Smart Caching: Results cached for 24 hours — no repeated API hits

🔍 **Post & Tag Search**

• Advanced Filtering: Search by tags, score, resolution, rating, uploader, pool, and more
• Full Tag Syntax: AND, OR, wildcard, exclusion, meta-tags, sorting, and pagination
• Tag Lookup: Check tag existence, post counts, and discover related tags

👥 **Community Tools**

• User Search: Find Gelbooru user accounts by name or wildcard pattern
• Comments: Retrieve post comments for any post ID
• Deleted Posts: Track removed content above a given post ID

📦 Installation

Prerequisites

• Python 3.10+
• git

Quick Start

1. Clone the repository:

git clone https://github.com/citronlegacy/gelbooru-mcp.git
cd gelbooru-mcp

2. Run the installer:

chmod +x install.sh && ./install.sh
# or without chmod:
bash install.sh

3. Or install manually:

pip install mcp

Note: Add .gelbooru_cache/ and .venv/ to your .gitignore to avoid committing cached data or your virtual environment.

Getting a Gelbooru API Key

1. Visit your Gelbooru account options page
2. Log in to your Gelbooru account
3. Copy your API Key and User ID
4. Set them as environment variables (see below)

🔑 Authentication

API credentials are optional but strongly recommended — unauthenticated requests are throttled and limited to 2 tags per query. Gelbooru Patreon supporters receive unlimited requests.

export GELBOORU_API_KEY="your_api_key"
export GELBOORU_USER_ID="your_user_id"

Both values are on your Gelbooru account options page. Without them the server still works but requests may be throttled. Patreon supporters of Gelbooru are not rate-limited.

▶️ Running the Server

python gelbooru_mcp.py
# or via the venv created by install.sh:
.venv/bin/python gelbooru_mcp.py

⚙️ Configuration

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

Other MCP Clients

Configure according to your client's documentation:

• Command: /absolute/path/to/.venv/bin/python
• Args: /absolute/path/to/gelbooru_mcp.py
• Transport: stdio

💡 Usage Examples

Generate a Stable Diffusion prompt for a character

"Build me a Stable Diffusion prompt for Rem from Re:Zero."

The LLM calls build_prompt with character_name: "rem_(re:zero)" and gets back:

rem (re:zero), blue eyes, blue hair, short hair, maid, maid headdress, maid apron, ...

Find high-quality wallpaper images

"Show me the top-rated scenery images that are at least 1920px wide."

The LLM calls search_posts with tags: "scenery width:>=1920 sort:score:desc".

Look up how popular a tag is

"How many posts does the tag 'misty_(pokemon)' have on Gelbooru?"

The LLM calls search_tags with name: "misty_(pokemon)" and reads the count field.

🛠️ Available Tools