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 个 MCP 工具：标签搜索、精确标签信息、相关标签、别名解析、Wiki 查询、帖子搜索和标签分布档案
• 标签分布档案：get_tag_profile 会从大型标签的帖子中随机抽取一页，并说明它实际呈现的内容——按样本频率统计共现标签（将 1girl/solo 等语料库常见标签归入 ubiquitous），并按提升度排列特征组合，因此在将 arm_up 这类有 30 万篇帖子的大标签加入提示词之前，可以先确认它是否符合你的实际需求
• 从帖子搜索获取标签列表：search_posts 会返回每篇帖子的完整标签列表，并按类别拆分（版权/艺术家/角色/通用/元数据），因此挖掘几篇帖子就能发现哪些标签通常会一起出现
• 检测标签器时代的标签：get_tag_info 会根据固定版本的 WD14 标签器词汇表对每个名称分类（wd14 字段：live / tagger_era——Danbooru 已重命名的标签器时代名称，可尝试 get_tag_alias / unknown），因此 LoRA 卡片说明不再卡在“未找到标签”；如果没有结果包含帖子，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 并以原子方式替换二进制文件
• 零配置安装：按用户安装程序（安装向导或一行 PowerShell 命令）会自动将安装目录注册到用户 PATH
• 遵守 API 使用规范：请求频率限制为每 1.5 秒一次；可匿名访问，凭据可提高限额（免费/匿名帖子搜索的每次查询仍最多只能使用 2 个内容标签）

安装

需要运行于 x64 或 ARM64 的 Windows 10/11。

选项 1：安装向导（推荐）

从最新版本 下载 danbooru-tag-mcp-windows-<arch>-setup.exe 并双击。它会按用户安装到 %LOCALAPPDATA%\Programs\danbooru-tag-mcp（无需管理员权限），并 注册用户 PATH。

选项 2：一行 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 用户，MCP 配置可以通过插件提供，而不必手动编辑 JSON：将此仓库添加为插件市场，并安装 danbooru-tag-mcp——该插件自带 danbooru-tags 服务定义，因此无需客户端配置。

• ZCode：插件市场 → 添加 → BaixuanZhu/danbooru-tag-mcp → 安装 danbooru-tag-mcp 插件。
• Claude Code：/plugin install danbooru-tag-mcp --marketplace BaixuanZhu/danbooru-tag-mcp （一步完成，需 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_hits（WD14 标签器词汇中包含该查询的名称）	query（必填，例如 blue hair）、limit（默认 10）
get_tag_info	获取单个标签的精确信息（类别、帖子数），以及 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 个帖子，涵盖整个总体——不筛选评级）：按样本内出现频率排序的 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* 标签后，GitHub Actions 会运行测试套件并发布两种架构的安装 exe、便携 zip 和 checksums.txt。