
danbooru-tag-mcp
io.github.BaixuanZhu/danbooru-tag-mcp
Danbooru MCP server for AI image generation: cached search, batch lookup, profiles, wiki, posts
Documentation
danbooru-tag-mcp
English | 简体中文
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/solosplit intoubiquitous, combinations ranked by lift, and the sample's rating mix.withprofiles a tag pair instead, answering whatarm_upplusholding_weaponrenders as. - Structured wiki pages — the DText body distilled into
summary,intro_tags,rules,see_alsoandexample_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) orunknown, 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:gfor all-ages only. - Built to stay installed — an on-disk cache that serves stale answers
during outages,
upgradeverifying 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 thedanbooru-tag-mcpplugin. - Claude Code:
/plugin install danbooru-tag-mcp --marketplace BaixuanZhu/danbooru-tag-mcp(one step, Claude Code 2.1.275+), or add the marketplace first withclaude plugin marketplace add BaixuanZhu/danbooru-tag-mcpand install from there.
danbooru-tag-mcp upgrade keeps the CLI updated independently of the plugin.
See plugins/danbooru-tag-mcp/README.md.
Tools
| Tool | What it does |
|---|---|
search_tags | Search tags by keyword, ordered by post count |
get_tag_info | Exact info for one tag, with a WD14 verdict on the name |
get_tags_info | The same for up to 20 names in one request |
get_related_tags | Tags that co-occur with a given tag |
get_tag_alias | Resolve an alias or misspelling to its canonical tag |
get_tag_wiki | A tag's wiki page as structured fields |
search_posts | Posts matching a tag combination, with their tag lists |
get_tag_profile | What a tag actually renders as, from a post sample |
Parameters and return fields for all eight tools
search_tags
query (required, e.g. blue hair) · limit (10) · category
(general/artist/copyright/character/meta) · min_posts (0, drops
tags below the threshold) · refresh (false)
When no result carries posts, the response adds wd14_hits — WD14 tagger
vocabulary names containing the query.
get_tag_info
name (required, e.g. blue_hair) · refresh (false)
Returns category and post count plus a wd14 verdict: live (current
Danbooru), tagger_era (WD14 vocabulary only, likely renamed — the canonical
name is in renamed_to) or unknown (neither). A 0-post name with an active
alias also returns renamed_to.
get_tags_info
names (required, e.g. ["blue_hair","1girl"], max 20) · refresh (false)
Returns found (each with the fields of get_tag_info, renamed_to
included on 0-post rows) and missing (absent from Danbooru, each still
carrying its wd14 verdict).
get_related_tags
tag (required) · limit (10) · refresh (false)
Meta-category tags like highres are filtered out as noise.
get_tag_alias
name (required, e.g. sailor_suit) · refresh (false)
null means the input is already canonical.
get_tag_wiki
title or other_names (one required) · limit (5) · include_description
(false) · refresh (false)
Returns summary (first paragraph), intro_tags (definition-section link
targets), rules (disambiguation and usage sentences), see_also,
example_posts, the raw linked_tags union and multilingual other_names.
The raw DText body is not returned; include_description adds the intro prose
as plain text, for character appearance descriptions.
search_posts
tags (required, space-separated) · limit (5, max 20) · tags_mode
(full default, none drops the per-post tag lists, diff keeps only tags
not already in the query)
No rating filter by default; add a rating:g/s/q/e metatag to narrow. Each
post carries score, fav_count, large_file_url and tags split by
category: copyright / artist / character / general / meta.
get_tag_profile
tag (required, e.g. arm_up) · sample (200, range 20-200) · with ·
rating (g/s/q/e) · order (random by default, or score /
favcount for a top-post view, which is biased)
Samples a page of the tag's posts and returns co_tags ordered by in-sample
frequency, ubiquitous corpus constants (freq >= 0.5), top_pairs
combinations ranked by lift, and the ratings mix. Random sampling covers the
whole population; rating filters the sample; with profiles the 200 most
recent joint posts of a tag pair instead.
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:
| Data | TTL |
|---|---|
Related tags (get_related_tags) | 30 days |
| Wiki pages, aliases | 7 days |
Tag searches (search_tags) | 24 hours |
Exact tag lookups (get_tag_info, get_tags_info) | 7 days |
Posts (search_posts, get_tag_profile) | never cached |
- 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: truepluscached_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_countcan trail live Danbooru by up to 7 days — userefresh: truewhen a decision needs current counts. refresh: truere-fetches live and restarts the entry's TTL clock.- Set
DANBOORU_MCP_NO_CACHE=1to 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 version
danbooru-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 bothDANBOORU_LOGINandDANBOORU_API_KEYare 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.0disables the gap; invalid values fall back to the default with a warning. Defaults: 1500 (anonymous) or 500 whenDANBOORU_LOGINandDANBOORU_API_KEYare 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 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)
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 manifest
gh attestation verify --repo BaixuanZhu/danbooru-tag-mcp danbooru-tag-mcp.exe # provenance
How the builds stay byte-reproducible, and how to rebuild one yourself →
No installation packages available.