danbooru-tag-mcp

danbooru-tag-mcp

English | 简体中文

[CI] [Release] [Platform] [Go] [License: MIT]

A Danbooru tag lookup MCP server for local AI image generation. Your AI client looks tags up instead of recalling them — exact names, aliases, categories, post counts, co-occurrence stats and wiki rules, resolved before it writes the prompt.

Windows 10/11 on x64 or ARM64. Anonymous access works, so there is no API key to obtain before the first query.

Quick start

Install per-user (Windows 10/11, no admin rights):

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

Point your MCP client at the command:

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

That's it — the client picks up the eight tools below on its next session.

What the client gets back

Live responses, abridged for length. Post counts move daily; these were captured on 2026-11-12.

search_tags for blue hair — the names that actually exist, so the model stops guessing bluehair:

{"tags": [  {"id": 10953, "name": "blue_hair", "category": 0, "post_count": 1234156},  {"id": 545704, "name": "blue_hairband", "category": 0, "post_count": 33332},  {"id": 1564040, "name": "blue_hair-chan_(ramchi)", "category": 4, "post_count": 120}]}

get_tag_info for blue_hair — the count, plus whether the WD14 taggers know the name at all:

{"id": 10953, "name": "blue_hair", "category": 0, "post_count": 1234156, "wd14": {"status": "live", "sources": [   {"vocab": "wd-eva02-large-tagger-v3", "count": 704952},   {"vocab": "wd-v1-4-moat-tagger-v2", "count": 564360}]}}

get_tag_profile for arm_up, all-ages sample of 200 — what the tag actually renders alongside, ranked by in-sample frequency, and which combinations are specific to it rather than merely common:

{"name": "arm_up", "post_count": 314588, "rating": "g", "sample": 200, "ratings": {"g": 1}, "ubiquitous": [   {"tag": "smile", "category": 0, "freq": 0.51},   {"tag": "solo", "category": 0, "freq": 0.51}], "co_tags": [   {"tag": "looking_at_viewer", "category": 0, "freq": 0.5},   {"tag": "long_sleeves", "category": 0, "freq": 0.48},   {"tag": "1girl", "category": 0, "freq": 0.46},   {"tag": "open_mouth", "category": 0, "freq": 0.45}], "top_pairs": [   {"pair": "pokemon + pokemon_(creature)", "freq": 0.05, "lift": 16.7},   {"pair": "japanese_clothes + kimono", "freq": 0.05, "lift": 15.4}]}

The full profile returns 30 co-occurring tags and 10 ranked pairs. Every field is documented under Tools.

Features

• 8 MCP tools — search tags, exact and batch lookup, aliases, related tags, wiki pages, post search, and distribution profiles.
• Batch lookup — 20 exact names in one call instead of 20, with a found/missing split and a WD14 verdict on every name.
• Distribution profiles — what a tag actually renders as: co-occurring tags by in-sample frequency, corpus constants like 1girl/solo split into ubiquitous, combinations ranked by lift, and the sample's rating mix. with profiles a tag pair instead, answering what arm_up plus holding_weapon renders as.
• Structured wiki pages — the DText body distilled into summary, intro_tags, rules, see_also and example_posts, so rules like "if X, use Y instead" arrive as data rather than prose to re-parse.
• Tagger-era detection — every name is checked against the pinned WD14 vocabularies and classified as live, tagger_era (renamed upstream, the canonical name included) or unknown, so LoRA card captions stop dead-ending at "tag not found".
• Post tag lists — each post comes back with its full tag list split by category, so mining a few posts shows which tags naturally go together. No rating filter by default; add rating:g for all-ages only.
• Built to stay installed — an on-disk cache that serves stale answers during outages, upgrade verifying SHA256 and swapping the binary atomically, a per-user installer that registers PATH, and 1.5 s request spacing (500 ms with credentials) that keeps anonymous access viable.

Tags come back as plain strings with no model coupling, so they paste straight into ComfyUI, Stable Diffusion or Illustrious prompt fields.

Install

Requires Windows 10/11 on x64 or ARM64. Every option installs per-user, needs no admin rights, and puts the install directory on the user PATH, so the bare danbooru-tag-mcp command works afterwards.

Option 1: setup wizard (recommended)

Download danbooru-tag-mcp-windows-<arch>-setup.exe from the latest release and double-click it. It installs to %LOCALAPPDATA%\Programs\danbooru-tag-mcp.

Option 2: one-line PowerShell

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

Custom install directory:

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

Option 3: portable zip

Download danbooru-tag-mcp-windows-<arch>.zip from the release page, extract danbooru-tag-mcp.exe anywhere, and run it once — the first run silently adds its own directory to the user PATH (idempotent).

Configure your MCP client

Point your MCP client (Claude Desktop, ZCode, etc.) at the command:

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

The bare command name works because the install directory is on the user PATH; alternatively use the full exe path.

Plugin instead of JSON (ZCode / Claude Code)

Add this repository as a plugin marketplace and install danbooru-tag-mcp — the plugin ships the danbooru-tags server definition, so there is no JSON to hand-edit. It wires configuration only: finish one of the install options above first, so the CLI is actually on PATH.

• ZCode: Plugin Marketplace → Add → BaixuanZhu/danbooru-tag-mcp → install the danbooru-tag-mcp plugin.
• Claude Code: /plugin install danbooru-tag-mcp --marketplace BaixuanZhu/danbooru-tag-mcp (one step, Claude Code 2.1.275+), or add the marketplace first with claude plugin marketplace add BaixuanZhu/danbooru-tag-mcp and install from there.

danbooru-tag-mcp upgrade keeps the CLI updated independently of the plugin. See plugins/danbooru-tag-mcp/README.md.

Tools

The six tag tools (search_tags, get_tag_info, get_tags_info, get_related_tags, get_tag_alias, get_tag_wiki) read from the response cache: repeat calls inside the TTL skip the network round trip, and during a Danbooru outage the last cached answer is served instead of an error, marked with stale: true and cached_at (when it was stored). Their refresh parameter (default false) bypasses the cache for a single call and re-fetches live. Post search and profiles are never cached, so they carry no refresh.

Response cache

Repeat queries are answered from an on-disk cache instead of hitting Danbooru again:

• Location: %LOCALAPPDATA%\danbooru-tag-mcp\cache (per user, persists across restarts, capped at 2000 entries / 64 MB with oldest-first eviction). It holds only API response bodies and is safe to delete at any time; the uninstaller removes it.
• Fresh hits are served byte-identically to a network response — no markers.
• When Danbooru is unreachable (after retries), the expired cached answer is served instead of an error, marked stale: true plus cached_at (when it was stored) on the affected tool response.
• Empty results ([]) are never cached, so new tags appear as soon as Danbooru knows them.
• Exact tag lookups keep a tag's identity row for 7 days (like wiki pages, name and category barely change), so post_count can trail live Danbooru by up to 7 days — use refresh: true when a decision needs current counts.
• refresh: true re-fetches live and restarts the entry's TTL clock.
• Set DANBOORU_MCP_NO_CACHE=1 to disable the cache entirely (useful for debugging).

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 versiondanbooru-tag-mcp help       show help

Environment variables

• DANBOORU_LOGIN — your Danbooru account name (the login you use on the site). Optional.
• DANBOORU_API_KEY — your Danbooru API key, generated from the API key section of your Danbooru profile. Optional. When both DANBOORU_LOGIN and DANBOORU_API_KEY are set, every request is sent authenticated with your account (higher rate limits and content access); otherwise the client is anonymous and Danbooru applies lower limits.
• DANBOORU_REQ_GAP_MS — minimum spacing between Danbooru requests, in milliseconds. 0 disables the gap; invalid values fall back to the default with a warning. Defaults: 1500 (anonymous) or 500 when DANBOORU_LOGIN and DANBOORU_API_KEY are both set.
• DANBOORU_MCP_NO_BOOTSTRAP — skip the startup PATH registration when non-empty.
• DANBOORU_MCP_NO_CACHE — disable the response cache when non-empty.

Building from source

Requires Go 1.26+ and GNU Make (bundled with Git Bash):

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

Releases are automated: pushing a v* tag makes GitHub Actions run the test suite and publish the setup exes, portable zips, and checksums.txt for both architectures.

Verifying a download

Binaries are not Authenticode-signed; integrity rests on reproducible builds, SHA-256 checksums and build provenance.

sha256sum -c --ignore-missing checksums.txt   # integrity vs the manifestgh attestation verify --repo BaixuanZhu/danbooru-tag-mcp danbooru-tag-mcp.exe   # provenance

How the builds stay byte-reproducible, and how to rebuild one yourself →