danbooru-tag-mcp

danbooru-tag-mcp

ローカルでのAI画像生成向けのDanbooruタグ検索MCP（Model Context Protocol）サーバーです。プロンプトを組み立てる前に、AIクライアントが実際のDanbooruタグ（正確な名前、別名、カテゴリ、投稿数、共起統計、Wikiの説明、実際の投稿に付いたタグ一覧）を解決するため、生成画像のタグ精度が目に見えて向上します。

クイックスタート

ユーザー単位でインストールします（Windows 10/11、管理者権限不要）：

iwr -useb "https://raw.githubusercontent.com/BaixuanZhu/danbooru-tag-mcp/main/install.ps1" | iex

MCPクライアントにコマンドを指定します：

{
  "mcpServers": {
    "danbooru-tags": {
      "command": "danbooru-tag-mcp",
      "args": []
    }
  }
}

これで完了です。次回のセッションから、クライアントで以下の7つのツールを利用できます。

機能

• 7つのMCPツール：タグ検索、タグの詳細情報、関連タグ、別名の解決、Wiki検索、投稿検索、タグ分布プロファイル
• タグ分布プロファイル：get_tag_profileは、投稿数の多いタグの投稿からランダムなページをサンプルし、実際にどのように描画されるかを示します。サンプル内の頻度で共起タグを集計し（1girl／soloなどのコーパス全体に広く見られる定数タグはubiquitousに分離）、さらに特徴的な組み合わせをリフト値順に表示します。これにより、arm_upのように30万件の投稿に使われるタグが、プロンプトに混ざる前に、本当に意図したものか確認できます。
• 投稿検索からタグ一覧を取得：search_postsは、各投稿の全タグをカテゴリ（copyright／artist／character／general／meta）別に分けて返します。数件の投稿を調べるだけで、自然に一緒に使われるタグがわかります。
• タグ付けツールの世代に由来するタグを検出：get_tag_infoは、ピン留めされたWD14タグ付けツールの語彙に照らしてすべての名前を分類します（wd14フィールド：live／tagger_era — Danbooruで名前が変更されたタグ付けツール時代の名前。get_tag_aliasを試してください／unknown）。これにより、LoRAカードのキャプションで「tag not found」と表示されて行き詰まることがなくなります。search_tagsは、投稿のある検索結果がない場合にwd14_hitsをフォールバックとして追加します。
• デフォルトで検閲なし：search_postsは評価フィルターを適用しないため、タグの投稿全体を反映した結果を返します（arm_upは約95％がg/s/qです）。R-18のみ、または全年齢向けのみの投稿を検索する場合は、rating:g/s/q/eメタタグを追加してください。
• 自動更新：danbooru-tag-mcp upgradeはGitHub Releasesを確認し、SHA256を検証して、バイナリをアトミックに置き換えます。
• 設定不要のインストール：ユーザー単位のインストーラー（セットアップウィザードまたは1行のPowerShell）により、インストールディレクトリがユーザーのPATHに自動登録されます。
• APIに配慮した利用：リクエストは1.5秒に1回に制限されます。匿名アクセスも可能で、認証情報を指定すると制限が緩和されます（無料／匿名での投稿検索は、クエリあたりコンテンツタグ2個までです）。

インストール

x64またはARM64のWindows 10/11が必要です。

オプション1：セットアップウィザード（推奨）

最新リリース からdanbooru-tag-mcp-windows-<arch>-setup.exeをダウンロードして、ダブルクリックします。ユーザー単位で%LOCALAPPDATA%\Programs\danbooru-tag-mcpにインストールされ（管理者権限は不要）、ユーザーのPATHに登録されます。

オプション2：1行のPowerShell

iwr -useb "https://raw.githubusercontent.com/BaixuanZhu/danbooru-tag-mcp/main/install.ps1" | iex

インストール先を指定する場合：

.\install.ps1 -InstallDir "D:\tools\danbooru-tag-mcp"

オプション3：ポータブルzip

リリースページ からdanbooru-tag-mcp-windows-<arch>.zipをダウンロードし、danbooru-tag-mcp.exeを任意の場所に展開して、一度実行します。初回実行時に、実行ファイルのあるディレクトリがユーザーのPATHに自動で追加されます（何度実行しても重複しません）。

オプション 4：ZCode／Claude Code プラグイン（MCP 設定を自動化）

ZCode および Claude Code のユーザーは、手作業で JSON を編集する代わりに、プラグインから MCP 設定を読み込めます。このリポジトリをプラグインマーケットプレイスとして追加し、danbooru-tag-mcp をインストールしてください。プラグインには danbooru-tags サーバー定義が含まれているため、クライアント側の設定は不要です。

• ZCode：Plugin Marketplace → Add → BaixuanZhu/danbooru-tag-mcp → danbooru-tag-mcp プラグインをインストールします。
• Claude Code：/plugin install danbooru-tag-mcp --marketplace BaixuanZhu/danbooru-tag-mcp （1 ステップで完了、Claude Code 2.1.275 以降）、または最初に claude plugin marketplace add BaixuanZhu/danbooru-tag-mcp でマーケットプレイスを追加してから、 そこからインストールします。

プラグインが設定するのは接続設定のみです。CLI は引き続き PATH 上にある必要があります （先に上記のオプション 1～3 のいずれかでインストールしてください）。また、 danbooru-tag-mcp upgrade を実行すると、プラグインとは別に CLI を最新の状態に保てます。詳しくは plugins/danbooru-tag-mcp/README.md をご覧ください。

MCP クライアントを設定する

MCP クライアント（Claude Desktop、ZCode など）に、次のコマンドを指定します。

{
  "mcpServers": {
    "danbooru-tags": {
      "command": "danbooru-tag-mcp",
      "args": []
    }
  }
}

インストール先のディレクトリがユーザー PATH に含まれているため、コマンド名だけで実行できます。 または exe のフルパスを使用してください。ZCode と Claude Code のユーザーは、 オプション 4 を利用すれば、 手動で JSON を設定する必要はありません。

ツール

ツール	説明	パラメーター
search_tags	キーワードでタグを検索し、投稿数順に並べます。投稿のある検索結果がない場合は、クエリを含む WD14 タガーの語彙名を wd14_hits として追加します	query（必須、例：blue hair）、limit（デフォルト：10）
get_tag_info	1 つのタグの正確な情報（カテゴリ、投稿数）と、wd14 の判定結果を返します。live（現在の Danbooru）、tagger_era（WD14 タガーの語彙のみ。名前が変更されている可能性があります。「get_tag_alias」を参照）、unknown（どちらにも該当しない）	name（必須、例：blue_hair）
get_related_tags	指定したタグと同時に使われるタグを返します（ノイズとなるメタカテゴリのタグ（highres など）は除外されます）	tag（必須）、limit（デフォルト：10）
get_tag_alias	エイリアスまたは誤字を正規タグに解決します（null は入力がすでに正規タグであることを示します）	name（必須、例：sailor_suit）
get_tag_wiki	タグの Wiki ページを返します。説明、多言語名、本文から抽出した [[tag]] リンクが含まれます	title または other_names（いずれか必須）、limit（デフォルト：5）
search_posts	タグの組み合わせで投稿を検索します。デフォルトではレーティングによる絞り込みはありません（絞り込むには rating:g/s/q/e メタタグを追加します）。各投稿の tags はカテゴリ別に分類されます：copyright／artist／character／general／meta	tags（必須、スペース区切り）、limit（デフォルト：5）
get_tag_profile	ランダムな投稿サンプル（デフォルトは 200 件、全投稿対象でレーティングによる絞り込みなし）から、1 つのタグの分布プロファイルを返します。co_tags はサンプル内の頻度順、ubiquitous はコーパス全体に共通するタグ（freq >= 0.5）、top_pairs はリフト値（偶然を上回る共起）順に並べた特徴的な組み合わせです。メタタグと対象のタグ自体は除外されます	tag（必須、例：arm_up）、sample（デフォルト：200、範囲：20～200）

CLI

danbooru-tag-mcp            run the MCP server (what MCP clients launch)
danbooru-tag-mcp upgrade    self-update via GitHub Release (SHA256 verified)
danbooru-tag-mcp version    print the version
danbooru-tag-mcp help       show help

環境変数

• DANBOORU_LOGIN — Danbooru のアカウント名（サイトへのログインに使う名前）です。任意です。
• DANBOORU_API_KEY — Danbooru の API キーです。Danbooru プロフィールの API キー欄から生成します。任意です。DANBOORU_LOGIN と DANBOORU_API_KEY の両方が設定されている場合、すべてのリクエストはアカウント認証付きで送信されます （より高いレート制限とコンテンツへのアクセスが可能になります）。それ以外の場合、クライアントは匿名となり、 Danbooru によって制限が厳しく設定されます。
• DANBOORU_MCP_NO_BOOTSTRAP — 空でない値を設定すると、起動時の PATH 登録をスキップします。

ソースからビルドする

Go 1.26 以降と GNU Make（Git Bash に同梱）が必要です。

make test        # unit tests
make integration # online smoke test against the live Danbooru API (~1 min)
make build       # dev build -> dist/<arch>/ (bootstrap disabled)
make release     # portable zip + checksums.txt
make installer   # NSIS setup exe (requires makensis: scoop install nsis)

リリースは自動化されています。v* タグを push すると、GitHub Actions がテストスイートを実行し、 両方のアーキテクチャ向けにセットアップ exe、ポータブル zip、checksums.txt を公開します。