⚠️ 纯 AI 生成声明 | Pure AI-Generated Notice

本项目代码由 AI（opencode + GLM-5.2）完全生成，未经人工编写。

This project's code is entirely generated by AI (opencode + GLM-5.2), without human-written code.

---

Danbooru Search MCP

English | 中文

---

<a id="english"></a>

English

An MCP (Model Context Protocol) server that searches Danbooru for anime/game characters and their related tags. Given a character tag like hoshino_(blue_archive), it returns the most relevant co-occurring tags (ahoge, pink_hair, blue_eyes, heterochromia, ...) ranked by how often they appear together.

Features

• Character profile in one call — visual traits, wiki description, multilingual aliases, and costume variant implications, all aggregated in parallel.
• Auto-correction — misspelled tags are automatically resolved via Danbooru's autocomplete (e.g. amamya_kokoro → amamiya_kokoro).
• No authentication required — the Danbooru read API is public. Setting DANBOORU_LOGIN / DANBOORU_API_KEY is optional and only raises your rate limit.
• Zero-install deployment — runs via uvx with no manual install step.

Tools

#	Tool	Purpose
1	danbooru_get_character_profile	⭐ Recommended first. Complete profile: traits + wiki + aliases + implications.
2	danbooru_search_character	Visual trait frequencies for a character tag (ahoge, pink_hair, etc.).
3	danbooru_lookup_tag	Find/verify a tag's exact canonical name. Alias-corrected.
4	danbooru_get_wiki_page	Get the textual wiki description for a tag.
5	danbooru_get_tag_implications	Get the implication chain (A → B auto-adds).

Requirements

• Python 3.10+
• uv (recommended) or pip

Install & Configure

Add this to your MCP client config (claude_desktop_config.json, opencode.json, etc.):

{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"]
    }
  }
}

From a local directory:

{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "E:\\path\\to\\Danbooru-Search-MCP", "danbooru-mcp"]
    }
  }
}

With optional authentication (higher rate limit):

{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"],
      "env": {
        "DANBOORU_LOGIN": "your_username",
        "DANBOORU_API_KEY": "your_api_key"
      }
    }
  }
}

Usage Examples

Ask your MCP-enabled assistant:

• "Search hoshino_(blue_archive), return the most relevant trait tags" → calls danbooru_search_character, returns ahoge (0.92), pink_hair (0.92), halo (0.93), ...
• "Give me the full profile of Amamiya Kokoro" → calls danbooru_get_character_profile with tag=amamiya_kokoro.
• "What does the ahoge tag mean?" → calls danbooru_get_wiki_page with title=ahoge.

Danbooru Tag Format

Tags use lowercase with underscores, and parentheses for disambiguation:

• Spaces → underscores: blue archive → blue_archive
• Disambiguation suffix: hoshino_(blue_archive), rem_(re:zero)

Use danbooru_lookup_tag with a * wildcard to discover the exact canonical name first.

Rate Limits

• Anonymous reads: 10 requests/second (shared global limit).
• With API key: higher per-account limits.
• The server sets a custom User-Agent as required by Danbooru's policy.

License

MIT

---

<a id="中文"></a>

中文

一个 MCP（模型上下文协议）服务器，通过 Danbooru 搜索动漫/游戏角色及其相关标签。输入角色标签如 hoshino_(blue_archive)，返回最相关的共现标签（ahoge、pink_hair、blue_eyes、heterochromia...），按共现频率排序。

功能特点

• 一次调用获取完整角色档案 — 视觉特征、Wiki 描述、多语言别名、服装变体蕴含关系，并行聚合。
• 自动纠错 — 拼写的标签名自动通过 Danbooru autocomplete 纠正（如 amamya_kokoro → amamiya_kokoro）。
• 无需认证 — Danbooru 只读 API 公开可用。设置 DANBOORU_LOGIN / DANBOORU_API_KEY 是可选的，仅用于提升限速。
• 零安装部署 — 通过 uvx 运行，无需手动安装。

工具列表

#	工具	用途
1	danbooru_get_character_profile	⭐ 推荐首选。 完整档案：特征 + Wiki + 别名 + 蕴含关系。
2	danbooru_search_character	获取角色视觉特征频率（ahoge、pink_hair 等）。
3	danbooru_lookup_tag	查找/验证标签的规范名称，支持别名纠错。
4	danbooru_get_wiki_page	获取标签的 Wiki 文字描述。
5	danbooru_get_tag_implications	获取标签蕴含链（A → B 自动附加）。

环境要求

• Python 3.10+
• uv（推荐）或 pip

安装与配置

将以下内容添加到 MCP 客户端配置中（claude_desktop_config.json、opencode.json 等）：

{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"]
    }
  }
}

从本地目录运行：

{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "E:\\path\\to\\Danbooru-Search-MCP", "danbooru-mcp"]
    }
  }
}

带认证（提升限速，可选）：

{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"],
      "env": {
        "DANBOORU_LOGIN": "你的用户名",
        "DANBOORU_API_KEY": "你的API密钥"
      }
    }
  }
}

使用示例

对支持 MCP 的 AI 助手说：

• "搜索 hoshino_(blue_archive)，返回最相关的特征标签" → 调用 danbooru_search_character，返回 ahoge（0.92）、pink_hair（0.92）、halo（0.93）...
• "给我天宫心（Amamiya Kokoro）的完整角色档案" → 调用 danbooru_get_character_profile，参数 tag=amamiya_kokoro。
• "ahoge 这个标签是什么意思？" → 调用 danbooru_get_wiki_page，参数 title=ahoge。

Danbooru 标签格式

标签使用小写 + 下划线，括号用于消歧：

• 空格 → 下划线：blue archive → blue_archive
• 消歧后缀：hoshino_(blue_archive)、rem_(re:zero)

不确定标签名时，先用 danbooru_lookup_tag 加 * 通配符查找。

限速

• 匿名读取：10 请求/秒（全站共享）。
• 带 API 密钥：更高的账户级限速。
• 服务器已设置 Danbooru 要求的自定义 User-Agent。

许可证

MIT