danbooru-tag-mcp

danbooru-tag-mcp

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

A Danbooru tag lookup MCP (Model Context Protocol) server for local AI image generation: your AI client resolves real Danbooru tags — exact names, aliases, categories, post counts, co-occurrence statistics, wiki descriptions, and the tag lists of real posts — before composing prompts, which noticeably improves tag accuracy in generated images.

[danbooru-tag-mcp demo: verifying Danbooru tags with search_tags, get_tag_wiki and search_posts before composing a prompt]

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.

Features

• 8 MCP tools: tag search, exact tag info, batch tag lookup, related tags, alias resolution, wiki lookup, post search, and tag distribution profiles
• Batch tag lookup: get_tags_info resolves up to 20 exact tag names in a single request — one tool call instead of 20, with found/missing split and a wd14 verdict on every name
• Tag distribution profiles, single or pair: get_tag_profile samples a page of a big tag's posts and answers what it 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 over the 200 most recent joint posts (what does arm_up + holding_weapon render as?); order: score/favcount switches to a top-post view (biased), rating: narrows either mode
• Structured wiki pages: get_tag_wiki distills the DText body into summary, intro_tags (definition/appearance tag targets), rules (the "if X, use Y instead" disambiguation sentences), see_also and example_posts — no raw body to re-parse; include_description opts into the intro prose as plain text for character appearance descriptions
• Tag lists back from post search: search_posts returns each post's full tag list split by category (copyright/artist/character/general/meta) plus score/fav_count/large_file_url, so mining a few posts reveals which tags naturally go together
• Tagger-era tag detection: get_tag_info classifies every name against the pinned WD14 tagger vocabularies (wd14 field: live / tagger_era — a tagger-era name Danbooru has since renamed, with the canonical name in renamed_to / unknown), so LoRA card captions stop dead-ending at "tag not found"; search_tags adds wd14_hits fallback hits when no result carries posts, and filters by category (general/artist/copyright/character/meta) so character or artist lookups stop drowning in general tags
• Uncensored by default: search_posts applies no rating filter — results reflect a tag's whole population (arm_up is ~95% g/s/q); add a rating:g/s/q/e metatag when you want only R-18 or only all-ages
• Self-updating: danbooru-tag-mcp upgrade checks GitHub Releases, verifies SHA256 and replaces the binary atomically
• Zero-config install: per-user installer (setup wizard or one-line PowerShell) that registers the install directory into the user PATH automatically
• Polite API usage: requests are throttled to one per 1.5 seconds; anonymous access works, credentials raise the limits (free/anonymous post searches are still capped at 2 content tags per query)

Install

Requires Windows 10/11 on x64 or ARM64.

Option 1: setup wizard (recommended)

Download danbooru-tag-mcp-windows-<arch>-setup.exe from the latest release and double-click it. This installs per-user to %LOCALAPPDATA%\Programs\danbooru-tag-mcp (no admin rights needed) and registers the user PATH.

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).

Option 4: ZCode / Claude Code plugin (auto MCP config)

For ZCode and Claude Code users the MCP configuration can come from a plugin instead of hand-edited JSON: add this repository as a plugin marketplace and install danbooru-tag-mcp — the plugin ships the danbooru-tags server definition, so no client-side config is needed.

• 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.

The plugin wires the configuration only — the CLI still has to be on PATH (install it first via Option 1-3 above), and danbooru-tag-mcp upgrade keeps it updated independently of the plugin. See plugins/danbooru-tag-mcp/README.md.

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. ZCode and Claude Code users can skip the manual JSON entirely via Option 4.

Tools

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_MCP_NO_BOOTSTRAP — skip the startup PATH registration 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.

Reproducible builds & verifying downloads

Release binaries are not Authenticode-signed; integrity rests on reproducible builds plus SHA-256, all free and verifiable by anyone:

• The exe and portable zips are byte-reproducible: the exact Go toolchain is pinned in go.mod, builds use CGO_ENABLED=0 -trimpath -buildvcs=false, and zips are written by scripts/zipfile with entry timestamps pinned to the commit time (SOURCE_DATE_EPOCH). Same source + toolchain ⇒ identical bytes on any machine, any timezone.
• Every release job runs a verify-repro check: it rebuilds the exe from the tagged source on a Linux runner and compares it byte-for-byte against the published Windows-built asset — a green check on the release proves the artifacts were built from the tag without tampering.
• All artifacts carry SHA-256 checksums (checksums.txt) and free keyless build-provenance attestations signed by the GitHub workflow.

Verify a download:

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

Reproduce the portable exe yourself and compare:

git checkout v0.4.0make build-dist VERSION=0.4.0 GOARCH=amd64sha256sum dist/amd64/danbooru-tag-mcp.exe     # must equal the hash inside the published zip

The NSIS setup exe is the one non-reproducible artifact (makensis embeds build metadata); it is still covered by checksums.txt and the attestations.