Pixabay MCP Server

pixabay-mcp-server

一个适用于 Pixabay API 的模型上下文协议（MCP）服务。它为 AI 助手——Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 以及任何 MCP 客户端——提供搜索和获取免版税图片与视频的工具。

重要

非官方项目。 本项目与 Pixabay 无关联，也未获得其认可或赞助。“Pixabay”是其各自所有者的商标。你使用自己的 Pixabay 账户访问本项目，并有责任遵守 Pixabay 服务条款和内容许可。

目录

• 功能
• 快速开始
• 交互示例
• 配置
• 工具
  • 工具参考
  • 输出格式
  • 资源和提示词
• 提示词示例
• 许可与合规
• 速率限制与缓存
• Pixabay 文本的处理
• 隐私与安全
• 故障排除
• 常见问题
• 要求
• 兼容性
• 路线图
• 贡献
• 联系与社区
• 许可

功能

• 涵盖 Pixabay 两个文档所述端点的 4 个工具——图片（搜索、获取）和视频（搜索、获取）。Pixabay 只有一个 API 密钥认证层级，且没有写入端点，因此不存在部分开放的“只读 v1”——这里涵盖了全部功能。
• 设计时充分考虑合规要求——每个发出的请求都会缓存 24 小时（这是 Pixabay 条款的要求，并非性能优化）；safesearch 默认设为 true；每项结果都会显示必要的致谢信息（by {user} via Pixabay），尽管 Pixabay 并未要求这样做。
• 提供真实的图片和视频 URL——搜索结果会为每个条目返回一个均衡的默认尺寸（图片使用 webformatURL，视频使用 medium 版本）；按 ID 查询特定条目时，则会返回 Pixabay 提供的所有尺寸，供你选择合适的版本。
• 输出节省令牌——将完整的 Pixabay 响应精简为紧凑格式（以文本形式呈现 URL 和元数据，绝不包含 base64 数据），并移除模型很少需要的虚荣指标（浏览量、下载量、点赞数、评论数）。
• 稳健可靠——返回类型化错误，并以 MCP isError 结果形式呈现，模型可据此恢复；对于 429/5xx、网络超时，会经过权衡后进行一次退避重试；日志也会考虑速率限制。
• 安全可靠——每条日志和错误消息都会隐藏 Pixabay API 密钥（由于 Pixabay 不支持请求头传递密钥，只能通过 URL 查询参数发送）。
• 轻量且现代——采用 ESM，支持 Node 20 及更高版本，可通过 npx 免安装运行，且不收集遥测数据。

快速开始

1. 获取 Pixabay API 密钥

注册一个免费的 pixabay.com 账户——登录后，API 密钥会立即显示在 API 文档页面上。本服务使用的默认套餐无需审批。

2. 将服务添加到 MCP 客户端

Claude Desktop — 编辑 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pixabay": {
      "command": "npx",
      "args": ["-y", "@hanoak/pixabay-mcp-server"],
      "env": {
        "PIXABAY_API_KEY": "your_api_key"
      }
    }
  }
}

重启客户端。有关所有受支持变量，请参阅配置。

claude mcp add pixabay \
  --env PIXABAY_API_KEY=your_api_key \
  -- npx -y @hanoak/pixabay-mcp-server

{
  "servers": {
    "pixabay": {
      "command": "npx",
      "args": ["-y", "@hanoak/pixabay-mcp-server"],
      "env": {
        "PIXABAY_API_KEY": "your_api_key"
      }
    }
  }
}

PIXABAY_API_KEY=your_api_key npx -y @hanoak/pixabay-mcp-server

3. 试用

重启客户端并提出以下请求：

“在 Pixabay 上帮我找一张山脉照片。”

示例交互

典型流程：模型调用 pixabay_search_images，选取一个结果，并附上来源说明来展示图片。

你： 找一张雾气弥漫的松林风景照。

助手： (调用 pixabay_search_images，参数为 query: "foggy pine forest"、 orientation: "horizontal"，并选取最佳结果) 这是一个很合适的结果——图片由 Josch13 上传至 Pixabay——并附有图片 URL。

每个工具都会返回紧凑的 JSON 负载。以下是单个搜索结果的结构示例 （数值仅供说明）：

[
  {
    "id": 195893,
    "pageURL": "https://pixabay.com/en/blossom-bloom-flower-195893/",
    "type": "photo",
    "tags": "blossom, bloom, flower",
    "url": "https://pixabay.com/get/35bbf209e13e39d2_640.jpg",
    "width": 640,
    "height": 360,
    "user": "Josch13",
    "attribution": "by Josch13 via Pixabay"
  }
]

配置

配置完全通过环境变量完成——无需配置文件，也无需用于密钥的命令行选项。

支持 CLI 标志：--version 和 --help（例如 npx @hanoak/pixabay-mcp-server --version）。

工具

所有工具都使用 pixabay_* 命名空间，且全部为只读——Pixabay 的 API 没有写入端点，因此客户端可以安全地自动批准整个服务。per_page 会限制在 Pixabay 文档规定的 3–200 范围内，page 从 1 开始计数。

工具参考

视频支持 category，但不支持 colors/orientation——这是 Pixabay 自身 API 的实际差异，并非疏漏。

输出格式

工具返回经过精简、节省 token 的 JSON，而非原始 Pixabay 响应：

• 图片搜索（pixabay_search_images）→ id、pageURL、type、tags、一个默认 url（webformatURL）、width/height、user、attribution。
• 图片详情（pixabay_get_image）→ 相同字段，外加 Pixabay 为该条目提供的所有尺寸级别： previewURL、webformatURL、largeImageURL、fullHDURL。
• 视频搜索（pixabay_search_videos）→ id、pageURL、type、tags、duration、一个 默认 url（medium 版本）、width/height、user、attribution。
• 视频详情（pixabay_get_video）→ 相同字段，外加一个 videos 对象，其中包含 Pixabay 提供的全部 四种版本（tiny/small/medium/large，每种都包含 url/width/ height）。
• 所有结果都会移除虚荣指标（views、downloads、likes、comments）——这些指标对模型 很少有用，只会增加 token，没有实际价值。

资源与提示词

除工具外，该服务还提供：

• 资源 — 客户端可将其作为上下文加载的精简指南：

  • pixabay://guides/usage — 许可证/署名指南、对话中热链接的相关说明、内容安全注意事项，以及完整 API 访问级别的限制说明。

• 提示词 — 客户端可直接呈现的现成任务：

  提示词	参数	功能
  find_media	subject（必填），media_type?（images|videos|both，默认 both）	搜索某个主题，并附上礼貌性署名，呈现最佳匹配结果。

提示词示例

可直接映射到工具的自然语言请求：

• “找一张日出时雾气弥漫的森林照片。”
• “在 Pixabay 上搜索 5 张极简风格的工作空间插画。”
• “找一段海浪拍打岩石的视频。”
• “给我 Pixabay 图片 195893 的最大可用版本。”

许可证与合规

Pixabay 内容依据 Pixabay 内容许可证发布： 可免费用于商业和非商业用途，无需署名。每个结果仍会包含可直接使用的礼貌性 attribution 字符串（by {user} via Pixabay）——方便时可注明，但不会以任何功能为前提。

该服务会将 Pixabay CDN URL 直接返回给调用它的 LLM 客户端，用于在单次对话轮次中显示。Pixabay 条款禁止在应用中“永久热链接”这些 URL——需要持久显示的内容应先下载并重新托管。我们认为 LLM 对话中的一次性临时显示不同于该使用场景，但 Pixabay 条款并未明确说明这一灰色地带（完整说明请参阅 src/tools/format.ts 顶部的注释）。如果你正在构建会存储或持久显示通过此服务获取的 Pixabay 内容的应用，请自行下载并重新托管素材——不要将此服务的工具输出视为替代方案。

每位用户都使用自己的 Pixabay 账户，并负责遵守 Pixabay 服务条款和 API 文档页面上的使用规则（缓存、速率限制、禁止批量下载）。本项目不会以任何方式更改或放宽这些条款。

速率限制与缓存

Pixabay 文档规定的限制是：每个 API 密钥每 60 秒约 100 次请求。此服务：

• 将每个响应缓存 24 小时，缓存键基于规范化后的请求（端点 + 排序后的参数，始终剔除 API 密钥）——重复查询会立即返回，不会消耗速率限制额度。根据 Pixabay 的条款，这是合规要求，而不只是优化措施。
• 从每个响应中读取 X-RateLimit-Remaining（以 debug 级别记录）。
• 遇到 429 时，使用 Pixabay 自己的 X-RateLimit-Reset 标头退避，且只尝试一次重试——绝不盲目重试或循环重试；如果缺少此标头，则快速失败，而不是自行猜测。
• 遇到 5xx 时也会重试一次（等待一小段固定时间，因为这种情况下服务器不会提供 X-RateLimit-Reset 之类的指导信息）。

Pixabay 文本的处理方式

图片／视频标签和贡献者用户名来自 Pixabay 社区——请将其视为不可信的第三方数据，而不是指令。服务仅将这些文本作为内容返回，绝不会将其放在任何特权位置；你的客户端／Agent 也应如此处理：可以显示文本，但不要执行其中可能包含的任何指令（以防范间接提示词注入）。

隐私与安全

• 不收集遥测数据。 此服务不会收集任何数据，也不会向任何人发送数据。它只会使用你提供的密钥连接 pixabay.com。不进行分析或跟踪。
• 密钥安全。 你的 API 密钥仅从环境中读取。Pixabay 只接受将密钥作为 key 查询参数传入（没有可替代的标头方式），因此密钥会在日志行和错误消息中被删除，绝不会泄露。
• 如需报告漏洞，请参阅 SECURITY.md。

故障排除

• 启动时显示“PIXABAY_API_KEY is not set…” —— 缺少密钥环境变量，或该变量为空；请将其添加到客户端配置的 env 块中。
• Node 版本过旧 —— 此服务需要 Node 20+。请检查 node --version。
• npx 版本过旧 —— 使用 npx -y @hanoak/pixabay-mcp-server@latest 强制获取最新版，或通过 npx clear-npx-cache 清除缓存。
• 未显示工具 —— 确认配置文件路径和 JSON 格式有效，然后完全退出并重新打开客户端。
• 429／速率限制 —— 额度约为每 60 秒 100 次请求；服务已使用 Pixabay 自己的重置时间自动退避并重试一次。
• 搜索结果显示“No images/videos found” —— 这是正常的空结果，并非错误；请尝试范围更广的查询或减少筛选条件。

常见问题

我需要付费的 Pixabay 帐户吗？ 不需要。Pixabay API 免费使用——只需创建帐户即可立即获取 API 密钥；此服务使用的默认层级无需审核或审批。

它会下载或重新托管图片／视频吗？ 不会。它会返回由 Pixabay 托管的 URL（临时显示时可直接引用这些链接——请参阅 许可与合规），绝不会重新托管或返回 base64 数据块。

为什么有些图片没有 fullHDURL／imageURL？ 这些字段需要单独申请 Pixabay 的“完整 API 访问”层级。此服务无需这些字段也能正常工作——未获得该访问权限的帐户，其搜索结果中不会包含这些字段。

它能在 Claude 之外使用吗？ 可以——这是一个标准的 stdio MCP 服务。请参阅客户端设置部分，了解 Claude Code、Cursor、VS Code、Windsurf 和通用 stdio 的配置方法。

要求

• Node.js >= 20（Node 18 已结束生命周期）。
• Pixabay API 密钥。

兼容性

路线图

详情请参阅 docs/ROADMAP.md。简而言之：v1 将在一个版本中涵盖 Pixabay 完整的文档化 API——无需 OAuth 层，因此不必拆分出 v2。正在考虑的未来范围包括用于许可/署名指南的 MCP 资源以及更多提示词。

变更记录见 CHANGELOG.md；本项目遵循 语义化版本规范。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 和我们的 行为准则。其中介绍了本地设置、测试套件、如何使用 MCP Inspector 手动测试工具，以及 版本管理/弃用政策。如需报告漏洞，请参阅 SECURITY.md。

联系方式与社区

由 Hanoak S 维护。获取帮助或提出功能建议的最快方式是 提交 issue——这里公开可见、可搜索， 也能帮助整个社区。

如果这个项目对你有所帮助，欢迎在 GitHub 上点亮 ⭐， 这有助于其他人发现这个 Pixabay MCP 服务。

许可证

MIT © Hanoak S。与 Pixabay 无关。