Gelbooru API 服务器

盖尔博鲁mcp

蟒蛇 主控程序 包装的服务器 黄钻API。将其连接到任何兼容MCP的客户端（Claude Desktop、Cursor等），以搜索帖子、查找标签，并从真实的角色外观数据生成稳定扩散提示——所有这些都可以直接从您的AI助手中完成。

✨ 特性

🎨 稳定扩散提示生成

• 角色提示：根据真实的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 以避免提交缓存数据或虚拟环境。

获取Gelboru API密钥

1. 访问您的 Gelbooru帐户选项页面
2. 登录您的Gelbooru帐户
3. 复制您的 API密钥 和 用户ID
4. 将它们设置为环境变量（见下文）

🔑 认证

API凭据是可选的，但强烈建议使用-未经身份验证的请求会受到限制，每个查询只能使用2个标签。Gelbooru Patreon的支持者收到无限的请求。

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

这两个值都在你的 Gelbooru帐户选项页面没有它们，服务器仍然可以工作，但请求可能会受到限制。盖尔博鲁的Patreon支持者不受利率限制。

▶️ 运行服务器

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

⚙️ 配置

克劳德桌面版

将以下内容添加到您的 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

💡 用法示例

为角色生成稳定扩散提示

“为Re:Zero中的Rem构建一个稳定的扩散提示。”

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

查看标签的受欢迎程度

“标签‘misty_（口袋妖怪）’在Gelbooru上有多少帖子？”

LLM电话 search_tags 随着 name: "misty_(pokemon)" 并阅读 count 现场。

🛠️ 可用工具

📖 工具参考

build_prompt

获取标记最多的 rating:general solo 发布一个字符，并组装一个即可粘贴的Stable Diffusion提示字符串。内部调用 get_character_tags 因此，结果在第一次获取后被缓存。

参数

示例响应

{
  "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_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的标签是情境性的。

缓存环境变量：

search_posts

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

参数

get_deleted_posts

检索已从Gelbooru删除的帖子，可选择过滤到给定帖子ID以上的帖子。

参数

search_tags

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

参数

LLM提示： 如果用户用自然语言给出角色名称（例如“口袋妖怪的迷雾”），请使用 name_pattern 随着 %misty%_(pokemon)% 在拨打电话之前找到正确的Gelbooru标签 get_character_tags 或 build_prompt.

search_users

按名称搜索Gelbooru用户帐户。

参数

get_comments

检索特定帖子的评论。

参数

🏷️ 标记语法参考

🤖 LLM注意事项

• 字符标签格式： Gelbooru使用 character_(series) 带下划线的格式。在传递给工具之前，始终转换自然语言名称——“Rem from Re:Zero”→ rem_(re:zero)《命运之剑》→ saber_(fate).
• 字符提示的工作流程： 如果确切的标签未知，请调用 search_tags 随着 name_pattern 第一→ 确认标签存在并有帖子→ 然后打电话 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 以获得干净、有代表性的外观数据。明确的帖子被设计排除在外。
• 缓存为per (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的支持者收到无限次请求

找不到字符/结果为空：

• 确认标签存在 search_tags 使用 name_pattern
• 检查拼写——Gelbooru使用 character_(series) 下划线格式
• 有些角色可能很少有一致标记的帖子

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

• 未经身份验证的用户每次查询最多只能有2个标签
• 使用API凭据对复杂的多标记搜索进行身份验证

🤝 贡献

欢迎拉取请求！如果您发现一个字符标签分类错误（例如，发筒中缺少发型标签，或者噪音标签通过净化过滤器），请使用标签及其所属列表打开问题或PR。

开发环境

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

📄 许可证

MIT许可证——见 许可证 了解详情。

🔗 链接

• 📚 API文件
• 🏷️ Gelbooru标签搜索备忘单
• 🔧 MCP文件
• 🐦 Gelbooru在X/推特上
• 🐛 错误报告
• 💡 功能请求和讨论