Gelbooru Mcp

gelbooru-mcp

Gelbooru APIをラップするPython製のMCPサーバーです。MCP対応クライアント（Claude Desktop、Cursorなど）に接続すると、投稿の検索、タグの確認、実際のキャラクターの外見データに基づくStable Diffusionプロンプトの生成を、すべてAIアシスタントから直接行えます。

---

✨ 機能

🎨 Stable Diffusionプロンプトの生成

• キャラクタープロンプト：Gelbooruの実際のタグ出現頻度データから、正確なSDプロンプトを自動生成します
• 外見の分類：目、髪、服装／アクセサリーのタグカテゴリを分けて表示します
• スマートキャッシュ：結果を24時間キャッシュするため、APIへの重複リクエストがありません

🔍 投稿とタグの検索

• 高度なフィルタリング：タグ、スコア、解像度、レーティング、アップロードユーザー、プールなどで検索します
• 完全なタグ構文：AND、OR、ワイルドカード、除外、メタタグ、並べ替え、ページネーションに対応します
• タグの確認：タグの存在や投稿数を確認し、関連タグを見つけます

👥 コミュニティツール

• ユーザー検索：名前またはワイルドカードパターンでGelbooruのユーザーアカウントを検索します
• コメント：任意の投稿IDの投稿コメントを取得します
• 削除済み投稿：指定した投稿IDより後の削除コンテンツを追跡します

---

📦 インストール

前提条件

• Python 3.10+
• git

クイックスタート

1. リポジトリをクローンします：

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

2. インストーラーを実行します：

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

3. または、手動でインストールします：

pip install mcp

注： キャッシュデータや仮想環境をコミットしないよう、.gelbooru_cache/と.venv/を.gitignoreに追加してください。

Gelbooru APIキーの取得

1. Gelbooruのアカウントオプションページにアクセスします
2. Gelbooruアカウントにログインします
3. API KeyとUser IDをコピーします
4. 環境変数として設定します（以下を参照）

---

🔑 認証

API認証情報は任意ですが、強く推奨します。未認証のリクエストは制限され、1回のクエリで指定できるタグは2つまでです。GelbooruのPatreonサポーターは、リクエスト数が無制限になります。

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

どちらの値もGelbooruのアカウントオプションページで確認できます。設定しなくてもサーバーは動作しますが、リクエストが制限される場合があります。GelbooruのPatreonサポーターはレート制限の対象外です。

---

▶️ サーバーの起動

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

---

⚙️ 設定

Claude Desktop

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

その他のMCPクライアント

クライアントのドキュメントに従って設定してください：

• コマンド：/absolute/path/to/.venv/bin/python
• 引数：/absolute/path/to/gelbooru_mcp.py
• トランスポート：stdio

---

💡 使用例

キャラクターのStable Diffusionプロンプトを生成する

「Re:ZeroのレムのStable Diffusionプロンプトを作ってください。」

LLMはcharacter_name: "rem_(re:zero)"を指定してbuild_promptを呼び出し、次の結果を受け取ります：

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

---

高品質な壁紙画像を探す

「幅が1920px以上の、評価が最も高い風景画像を表示してください。」

LLMはtags: "scenery width:>=1920 sort:score:desc"を指定してsearch_postsを呼び出します。

---

タグの人気を確認する

「Gelbooruに'misty_(pokemon)'というタグが付いた投稿はいくつありますか？」

LLMはname: "misty_(pokemon)"を指定してsearch_tagsを呼び出し、countフィールドを読み取ります。

---

🛠️ 利用可能なツール

ツール	説明	主なパラメーター
build_prompt	キャラクター用の Stable Diffusion プロンプト文字列を生成します	character_name、max_images、include_other
get_character_tags	出現頻度を含む、構造化されたタグの内訳を取得します	character_name、max_images
search_posts	タグ構文を完全にサポートして投稿を検索します	tags、limit、pid、id
search_tags	名前、パターン、ID でタグを検索します	name、name_pattern、orderby、limit
search_users	Gelbooru のユーザーアカウントを検索します	name、name_pattern、limit
get_comments	投稿のコメントを取得します	post_id
get_deleted_posts	最近削除された投稿の一覧を取得します	last_id、limit

---

📖 ツールリファレンス

build_prompt

キャラクターについて、最も多くタグが付けられた rating:general solo の投稿を取得し、そのまま貼り付けられる Stable Diffusion プロンプト文字列を組み立てます。内部で get_character_tags を呼び出すため、初回の取得後は結果がキャッシュされます。

パラメーター

パラメーター	型	必須	デフォルト	説明
character_name	string	✅	—	Gelbooru のキャラクタータグ。例：misty_(pokemon)
max_images	integer	❌	300	分析する投稿数です。数が多いほど初回の取得に時間がかかりますが、タグの信頼性が高まります。取得後はキャッシュされます。
include_other	boolean	❌	true	目や髪以外のタグ（服、アクセサリーなど）を含めます。外見のみのプロンプトにする場合は false に設定します。

応答例

{
  "prompt": {
    "character": "misty (pokemon)",
    "posts_analysed": 284,
    "cache_hit": false,
    "prompt_string": "misty (pokemon), green eyes, orange hair, side ponytail, gym leader, shorts, suspenders",
    "tags": {
      "eye":   ["green eyes"],
      "hair":  ["orange hair", "side ponytail"],
      "other": ["gym leader", "shorts", "suspenders"]
    }
  }
}

LLM のヒント： Gelbooru のアンダースコア形式（Misty (Pokemon) ではなく misty_(pokemon)）を必ず使用してください。正確なタグがわからない場合は、まず name_pattern を指定して search_tags を呼び出してください。

---

get_character_tags

build_prompt と同じデータソースを使用しますが、出現頻度を含む、構造化されたタグの内訳全体を返します。タグを自分で確認、絞り込み、または再フォーマットする場合に使用してください。

パラメーター

パラメーター	型	必須	デフォルト	説明
character_name	string	✅	—	Gelbooru のキャラクタータグ。例：rem_(re:zero)
max_images	integer	❌	300	分析するスコア上位の投稿数です。

応答例

{
  "character_tags": {
    "name": "rem_(re:zero)",
    "posts_analysed": 300,
    "cache_hit": true,
    "eye": [
      { "tag": "blue eyes", "count": 261, "frequency": 0.87 }
    ],
    "hair": [
      { "tag": "blue hair",  "count": 274, "frequency": 0.913 },
      { "tag": "short hair", "count": 198, "frequency": 0.66  }
    ],
    "other": [
      { "tag": "maid", "count": 231, "frequency": 0.77 }
    ]
  }
}

frequency は、そのタグが分析対象の投稿に付いていた割合（0.0～1.0）です。1.0 に近いタグはほぼすべての投稿に共通し、0.3 未満のタグは特定の状況でのみ見られます。

キャッシュ環境変数：

環境変数	デフォルト	説明
GELBOORU_CACHE_DIR	スクリプトと同じ場所の .gelbooru_cache/	カスタムキャッシュフォルダーのパス
GELBOORU_CACHE_TTL	86400（24 時間）	キャッシュの有効期間（秒）

---

search_posts

任意のタグの組み合わせを使用して、Gelbooru の投稿を検索します。メタタグ、並べ替え、フィルタリングを含む、Gelbooru のタグ構文全体をサポートします。

パラメーター

パラメーター	型	必須	デフォルト	説明
tags	string	❌	—	タグ検索文字列（下記のタグ構文リファレンスを参照）
limit	integer	❌	20	返す投稿数（最大 100）
pid	integer	❌	0	ページ番号（0 始まり）
id	integer	❌	—	Gelbooru の投稿 ID を指定して単一の投稿を取得します
cid	integer	❌	—	変更 ID（Unix タイムスタンプ）を指定して投稿を取得します

---

get_deleted_posts

Gelbooru から削除された投稿を取得します。必要に応じて、指定した投稿 ID より大きいものに絞り込めます。

パラメーター

パラメーター	型	必須	デフォルト	説明
last_id	integer	❌	—	この値より大きい ID の削除済み投稿のみを返します。ローカルミラーとの同期に便利です。
limit	integer	❌	20	返す投稿数（最大 100）

---

search_tags

Gelbooru のタグを名前、ワイルドカードパターン、または ID で検索します。タグの存在確認、投稿数の確認、関連タグの発見、オートコンプリートに役立ちます。

パラメーター

パラメーター	型	必須	デフォルト	説明
name	string	❌	—	正確なタグ名。例：blue_hair
names	string	❌	—	正確なタグ名をスペース区切りで並べたリスト。例：cat_ears dog_ears fox_ears
name_pattern	string	❌	—	SQL LIKE ワイルドカード：% = 任意の文字列、_ = 1 文字。例：%schoolgirl%
id	integer	❌	—	データベース ID でタグを検索します
after_id	integer	❌	—	この値より大きい ID のタグを返します
limit	integer	❌	20	返すタグ数（最大 100）
order	string	❌	—	ASC または DESC
orderby	string	❌	—	並べ替えフィールド：date、count、name

LLM 向けヒント： ユーザーが自然言語でキャラクター名を指定した場合（例：「Pokemon の Misty」）、get_character_tags または build_prompt を呼び出す前に、name_pattern で %misty%_(pokemon)% を使って正しい Gelbooru タグを検索してください。

---

search_users

Gelbooru のユーザーアカウントを名前で検索します。

パラメーター

パラメーター	型	必須	デフォルト	説明
name	string	❌	—	正確なユーザー名
name_pattern	string	❌	—	SQL LIKE ワイルドカードによるユーザー名検索
limit	integer	❌	20	返す結果数（最大 100）
pid	integer	❌	0	ページネーション用のページ番号

---

get_comments

特定の投稿に付いたコメントを取得します。

パラメーター

パラメーター	型	必須	デフォルト	説明
post_id	integer	✅	—	コメントを取得する Gelbooru の投稿 ID

---

🏷️ タグ構文リファレンス

構文	意味
tag1 tag2	tag1 と tag2 の両方が付いた投稿
{tag1 ~ tag2 ~ tag3}	tag1、tag2、または tag3 が付いた投稿
-tag1	tag1 が付いた投稿を除外
*tag1	ワイルドカード接頭辞（tag1 で終わるタグ）
tag1*	ワイルドカード接尾辞（tag1 で始まるタグ）
rating:general	レーティングで絞り込み：general、questionable、または explicit
-rating:explicit	レーティングを除外
score:>=50	スコアが 50 以上
width:>=1920	画像の幅が 1920px 以上
height:>1080	画像の高さが 1080px より大きい
user:bob	ユーザー「bob」がアップロード
fav:1	ID 1 のユーザーがお気に入りに追加した投稿
pool:2	プール ID 2 の投稿
sort:score:desc	スコアで並べ替え（降順または昇順）
sort:random	リクエストごとにランダムな順序
sort:random:1234	固定シード（0～10000）でランダムな順序
sort:updated:desc	更新日時が新しい順に並べ替え

---

🤖 LLM 向けの注意事項

• キャラクタータグの形式： Gelbooru では、アンダースコアを使った character_(series) 形式を使用します。ツールに渡す前に、自然言語の名前を必ず変換してください。「Re:Zero の Rem」→ rem_(re:zero)、「Fate の Saber」→ saber_(fate)。
• キャラクタープロンプトのワークフロー： 正確なタグが不明な場合は、まず name_pattern を指定して search_tags を呼び出し、タグの存在と投稿があることを確認してから build_prompt を呼び出してください。
• ページネーション： search_posts が 1 回の呼び出しで返す結果は最大 100 件です。pid を使ってページを順に確認してください。get_character_tags と build_prompt は内部でページネーションを処理します。
• キャッシュ： get_character_tags と build_prompt は結果を 24 時間キャッシュします。レスポンスの cache_hit フィールドは、ライブデータとキャッシュデータのどちらが使用されたかを示します。
• レーティング： Gelbooru では general、questionable、explicit を使用します。get_character_tags と build_prompt は、より明確で代表的なキャラクターデータを得るため、常に rating:general で絞り込みます。

---

⚠️ 既知の制限事項

• タグ検索の上限： Gelbooruでは、未認証の検索クエリで使用できるタグは最大2つです。複雑な複数タグのクエリを使用する場合は、GELBOORU_API_KEY と GELBOORU_USER_ID を設定してください。
• get_character_tags の精度： 結果は、Gelbooruでキャラクターのタグ付けがどれだけ一貫して行われているかによって異なります。ニッチなキャラクターや最近追加されたキャラクターは、投稿数が少なく、頻度データの信頼性も低い場合があります。
• キャラクター用ツールでは rating:general のみ： build_prompt と get_character_tags は、クリーンで代表的な外見データを取得するため、意図的に rating:general に制限しています。露骨な投稿は仕様上、除外されます。
• キャッシュは (character_name, max_images) の組み合わせごとです： max_images を変更すると、そのキャラクターのキャッシュは無効になります。

---

🐛 トラブルシューティング

サーバーが起動しない場合：

• Python 3.10+ がインストールされていることを確認してください：python --version
• 仮想環境が作成されていることを確認してください：ls .venv/
• インストーラーを再実行してください：bash install.sh

API のレート制限／リクエストのスロットリング：

• 環境変数 GELBOORU_API_KEY と GELBOORU_USER_ID を設定してください
• Gelbooru の Patreon 支援者はリクエストを無制限に行えます

キャラクターが見つからない／結果が空の場合：

• name_pattern を指定して search_tags を使い、タグが存在することを確認してください
• スペルを確認してください。Gelbooruでは character_(series) のアンダースコア形式が使われています
• 一貫してタグ付けされた投稿が非常に少ないキャラクターもいます

タグ構文エラー／タグ数が多すぎる場合：

• 未認証ユーザーが1つのクエリで使用できるタグは2つまでです
• 複雑な複数タグ検索には、API 認証情報で認証してください

---

🤝 コントリビューション

プルリクエストを歓迎します！キャラクタータグの分類に誤りがある場合（例：髪型タグが髪のバケットから欠落している、ノイズタグが除外フィルターをすり抜けるなど）は、そのタグと該当するリストを添えて、issue または PR を作成してください。

開発環境のセットアップ

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. プルリクエストを送信します

---

📄 ライセンス

MIT License — 詳細は LICENSE を参照してください。

---

🔗 リンク

• 📚 Gelbooru API ドキュメント
• 🏷️ Gelbooru タグ検索チートシート
• 🔧 MCP ドキュメント
• 🐦 X/Twitter の Gelbooru
• 🐛 バグ報告
• 💡 機能リクエストとディスカッション