Gelbooru Mcp

gelbooru-mcp

一个封装了 Gelbooru API 的 Python MCP 服务。将其连接到任何兼容 MCP 的客户端（Claude Desktop、Cursor 等），即可直接通过 AI 助手搜索帖子、查找标签，并根据真实的角色外观数据生成 Stable Diffusion 提示词。

---

✨ 功能

🎨 Stable Diffusion 提示词生成

• 角色提示词：根据 Gelbooru 真实标签频率数据自动生成准确的 SD 提示词
• 外观细分：分别整理眼睛、头发和服装/配饰标签类别
• 智能缓存：结果缓存 24 小时，避免重复调用 API

🔍 帖子和标签搜索

• 高级筛选：按标签、评分、分辨率、评级、上传者、图库等搜索
• 完整标签语法：支持 AND、OR、通配符、排除、元标签、排序和分页
• 标签查找：检查标签是否存在、查看帖子数量并发现相关标签

👥 社区工具

• 用户搜索：按名称或通配符模式查找 Gelbooru 用户账号
• 评论：获取任意帖子 ID 对应的帖子评论
• 已删除帖子：跟踪指定帖子 ID 以上的已删除内容

---

📦 安装

前置条件

• Python 3.10+
• git

快速开始

1. 克隆代码库：

git clone https://github.com/citronlegacy/gelbooru-mcp.git
cd gelbooru-mcp

2. 运行安装程序：

chmod +x install.sh && ./install.sh
# or without chmod:
bash install.sh

3. 或手动安装：

pip install mcp

注意： 将 .gelbooru_cache/ 和 .venv/ 添加到 .gitignore，以避免提交缓存数据或虚拟环境。

获取 Gelbooru API 密钥

1. 访问你的 Gelbooru 账号选项页面
2. 登录你的 Gelbooru 账号
3. 复制你的 API Key 和 User ID
4. 将它们设为环境变量（见下文）

---

🔑 身份验证

API 凭据为可选项，但强烈建议配置——未经身份验证的请求会受到限流，并且每次查询最多只能使用 2 个标签。Gelbooru Patreon 支持者可无限次请求。

export GELBOORU_API_KEY="your_api_key"
export GELBOORU_USER_ID="your_user_id"

这两个值都可以在你的 Gelbooru 账号选项页面找到。没有它们，服务仍可运行，但请求可能会受到限流。Gelbooru 的 Patreon 支持者不受速率限制。

---

▶️ 运行服务

python gelbooru_mcp.py
# or via the venv created by install.sh:
.venv/bin/python gelbooru_mcp.py

---

⚙️ 配置

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "gelbooru-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/gelbooru_mcp.py"],
      "env": {
        "GELBOORU_API_KEY": "your_api_key",
        "GELBOORU_USER_ID": "your_user_id"
      }
    }
  }
}

其他 MCP 客户端

根据客户端文档进行配置：

• 命令：/absolute/path/to/.venv/bin/python
• 参数：/absolute/path/to/gelbooru_mcp.py
• 传输方式：stdio

---

💡 使用示例

为某个角色生成 Stable Diffusion 提示词

“帮我为《Re:Zero》中的 Rem 生成 Stable Diffusion 提示词。”

LLM 会调用 build_prompt，参数为 character_name: "rem_(re:zero)"，并返回：

rem (re:zero), blue eyes, blue hair, short hair, maid, maid headdress, maid apron, ...

---

查找高质量壁纸图片

“给我看看评分最高、宽度至少为 1920px 的风景图片。”

LLM 会调用 search_posts，参数为 tags: "scenery width:>=1920 sort:score:desc"。

---

查询标签的热度

“Gelbooru 上有多少个带有标签 'misty_(pokemon)' 的帖子？”

LLM 会调用 search_tags，参数为 name: "misty_(pokemon)"，并读取 count 字段。

---

🛠️ 可用工具

工具	描述	关键参数
build_prompt	为角色生成 Stable Diffusion 提示词字符串	character_name、max_images、include_other
get_character_tags	获取带频次统计的结构化标签细分	character_name、max_images
search_posts	搜索帖子，支持完整的标签语法	tags、limit、pid、id
search_tags	按名称、模式或 ID 查找标签	name、name_pattern、orderby、limit
search_users	查找 Gelbooru 用户账号	name、name_pattern、limit
get_comments	获取帖子的评论	post_id
get_deleted_posts	列出最近删除的帖子	last_id、limit

---

📖 工具参考

build_prompt

获取某个角色标签最多的 rating:general solo 帖子，并整理成可直接粘贴的 Stable Diffusion 提示词字符串。此工具内部会调用 get_character_tags，因此首次获取后结果会被缓存。

参数

参数	类型	必填	默认值	描述
character_name	string	✅	—	Gelbooru 角色标签，例如 misty_(pokemon)
max_images	integer	❌	300	要分析的帖子数量。数量越多，首次获取越慢，标签也越可靠。之后会缓存结果。
include_other	boolean	❌	true	是否包含非眼睛／头发类标签（服装、配饰等）。设为 false 可仅生成外观提示词。

示例响应

{
  "prompt": {
    "character": "misty (pokemon)",
    "posts_analysed": 284,
    "cache_hit": false,
    "prompt_string": "misty (pokemon), green eyes, orange hair, side ponytail, gym leader, shorts, suspenders",
    "tags": {
      "eye":   ["green eyes"],
      "hair":  ["orange hair", "side ponytail"],
      "other": ["gym leader", "shorts", "suspenders"]
    }
  }
}

LLM 提示： 始终使用 Gelbooru 的下划线格式（misty_(pokemon)，而非 Misty (Pokemon)）。如果不确定准确标签，请先调用 search_tags 并使用 name_pattern。

---

get_character_tags

数据来源与 build_prompt 相同，但会返回带频次统计的完整结构化标签细分。如果你想自行检查、筛选或重新整理标签，请使用此工具。

参数

参数	类型	必填	默认值	描述
character_name	string	✅	—	Gelbooru 角色标签，例如 rem_(re:zero)
max_images	integer	❌	300	要分析的高分帖子数量。

示例响应

{
  "character_tags": {
    "name": "rem_(re:zero)",
    "posts_analysed": 300,
    "cache_hit": true,
    "eye": [
      { "tag": "blue eyes", "count": 261, "frequency": 0.87 }
    ],
    "hair": [
      { "tag": "blue hair",  "count": 274, "frequency": 0.913 },
      { "tag": "short hair", "count": 198, "frequency": 0.66  }
    ],
    "other": [
      { "tag": "maid", "count": 231, "frequency": 0.77 }
    ]
  }
}

frequency 是包含该标签的已分析帖子所占比例（0.0–1.0）。接近 1.0 的标签几乎普遍出现；低于 0.3 的标签则只在特定情况下出现。

缓存环境变量：

环境变量	默认值	描述
GELBOORU_CACHE_DIR	.gelbooru_cache/（与脚本位于同一目录）	自定义缓存文件夹路径
GELBOORU_CACHE_TTL	86400（24 小时）	缓存有效期（秒）

---

search_posts

使用任意标签组合搜索 Gelbooru 帖子。支持完整的 Gelbooru 标签语法，包括元标签、排序和筛选。

参数

参数	类型	必填	默认值	描述
tags	string	❌	—	标签查询字符串（参见下方的标签语法参考）
limit	integer	❌	20	返回的帖子数量（最多 100）
pid	integer	❌	0	用于分页的页码（从 0 开始）
id	integer	❌	—	根据 Gelbooru 帖子 ID 获取单个帖子
cid	integer	❌	—	根据更改 ID（Unix 时间戳）获取帖子

---

get_deleted_posts

获取已从 Gelbooru 删除的帖子，也可以按指定帖子 ID 筛选，只返回 ID 较大的帖子。

参数

参数	类型	必填	默认值	描述
last_id	integer	❌	—	仅返回 ID 大于此值的已删除帖子。适用于同步本地镜像。
limit	integer	❌	20	返回的帖子数量（最多 100）

---

search_tags

按名称、通配符模式或 ID 查找 Gelbooru 标签。可用于检查标签是否存在、查找帖子数、发现相关标签或自动补全。

参数

参数	类型	必填	默认值	描述
name	string	❌	—	完整标签名称，例如 blue_hair
names	string	❌	—	以空格分隔的完整标签名称列表，例如 cat_ears dog_ears fox_ears
name_pattern	string	❌	—	SQL LIKE 通配符：% = 任意字符，_ = 单个字符。例如 %schoolgirl%
id	integer	❌	—	按数据库 ID 查找标签
after_id	integer	❌	—	返回 ID 大于此值的标签
limit	integer	❌	20	返回的标签数（最多 100）
order	string	❌	—	ASC 或 DESC
orderby	string	❌	—	排序字段：date、count 或 name

LLM 提示： 如果用户用自然语言提供角色名称（例如“来自 Pokemon 的 Misty”），请使用 name_pattern 和 %misty%_(pokemon)% 查找正确的 Gelbooru 标签，然后再调用 get_character_tags 或 build_prompt。

---

search_users

按名称搜索 Gelbooru 用户账号。

参数

参数	类型	必填	默认值	描述
name	string	❌	—	完整用户名
name_pattern	string	❌	—	使用 SQL LIKE 通配符搜索用户名
limit	integer	❌	20	返回的结果数（最多 100）
pid	integer	❌	0	分页页码

---

get_comments

获取指定帖子的评论。

参数

参数	类型	必填	默认值	描述
post_id	integer	✅	—	要获取评论的 Gelbooru 帖子 ID

---

🏷️ 标签语法参考

语法	含义
tag1 tag2	同时包含 tag1 和 tag2 的帖子
{tag1 ~ tag2 ~ tag3}	包含 tag1、tag2 或 tag3 的帖子
-tag1	排除包含 tag1 的帖子
*tag1	前缀通配符（以 tag1 结尾的标签）
tag1*	后缀通配符（以 tag1 开头的标签）
rating:general	按评级筛选：general、questionable 或 explicit
-rating:explicit	排除某个评级
score:>=50	评分至少为 50
width:>=1920	图片宽度 ≥ 1920px
height:>1080	图片高度 > 1080px
user:bob	由用户“bob”上传
fav:1	用户 ID 为 1 的用户收藏的帖子
pool:2	ID 为 2 的合集中的帖子
sort:score:desc	按评分排序（降序或升序）
sort:random	每次请求均随机排序
sort:random:1234	使用固定种子随机排序（0–10000）
sort:updated:desc	按最近更新时间排序

---

🤖 给 LLM 的说明

• 角色标签格式： Gelbooru 使用 character_(series) 格式，并以下划线分隔。传给工具前，务必将自然语言名称转换为此格式：“来自 Re:Zero 的 Rem” → rem_(re:zero)，“来自 Fate 的 Saber” → saber_(fate)。
• 角色提示词工作流： 如果不知道准确标签，请先使用 name_pattern 调用 search_tags → 确认标签存在且有帖子 → 然后调用 build_prompt。
• 分页： search_posts 每次调用最多返回 100 条结果。使用 pid 浏览不同页面。get_character_tags 和 build_prompt 会在内部处理分页。
• 缓存： get_character_tags 和 build_prompt 会缓存结果 24 小时。响应中的 cache_hit 字段表示使用的是实时数据还是缓存数据。
• 评级： Gelbooru 使用 general、questionable 和 explicit。get_character_tags 和 build_prompt 始终筛选 rating:general，以获得更简洁、更具代表性的角色数据。

---

⚠️ 已知限制

• 标签搜索限制： Gelbooru 对未认证的搜索查询最多允许 2 个标签。对于复杂的多标签查询，请设置 GELBOORU_API_KEY 和 GELBOORU_USER_ID。
• get_character_tags 的准确性： 结果取决于 Gelbooru 上对角色打标签的一致性。小众或最近添加的角色可能帖子较少，频率数据也不太可靠。
• 角色工具仅使用 rating:general： build_prompt 和 get_character_tags 会有意限制为 rating:general，以获取干净且有代表性的外观数据。设计上不包含露骨内容的帖子。
• 缓存按 (character_name, max_images) 组合分别保存： 更改 max_images 会使该角色的缓存失效。

---

🐛 故障排除

服务无法启动：

• 确保已安装 Python 3.10+：python --version
• 确认已创建虚拟环境：ls .venv/
• 重新运行安装程序：bash install.sh

API 请求频率限制 / 请求被限流：

• 设置 GELBOORU_API_KEY 和 GELBOORU_USER_ID 环境变量
• Gelbooru Patreon 支持者可无限制地发送请求

找不到角色 / 结果为空：

• 使用 name_pattern 通过 search_tags 确认标签是否存在
• 检查拼写——Gelbooru 使用 character_(series) 下划线格式
• 某些角色可能只有少量打标一致的帖子

标签语法错误 / 标签过多：

• 未认证用户的每次查询最多只能使用 2 个标签
• 使用 API 凭据进行认证，以执行复杂的多标签搜索

---

🤝 参与贡献

欢迎提交拉取请求！如果你发现角色标签分类有误（例如，发型标签未被归入发型类别，或噪声标签未被清理筛选器过滤），请提交问题或 PR，并注明该标签及其所属列表。

开发环境设置

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 提交拉取请求

---

📄 许可证

MIT 许可证——详情请参阅 LICENSE。

---

🔗 链接

• 📚 Gelbooru API 文档
• 🏷️ Gelbooru 标签搜索速查表
• 🔧 MCP 文档
• 🐦 Gelbooru 在 X/Twitter 上的主页
• 🐛 错误报告
• 💡 功能请求与讨论