pixabay-mcp MCP 服务器

中文版

这是一个用于 Pixabay 图像和视频搜索的 Model Context Protocol (MCP) 服务器，提供结构化结果及运行时验证。

<a href="https://glama.ai/mcp/servers/@zym9863/pixabay-mcp"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=912592215,2706100564&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Pixabay Server MCP 服务器" /> </a>

这个 TypeScript MCP 服务器通过标准 I/O 暴露了 Pixabay 搜索工具，使得 AI 助手/代理能够安全可靠地检索媒体内容。

亮点：

• 图像与视频搜索工具（Pixabay 官方 API）
• 运行时参数验证（枚举、范围、语义检查）
• 一致的日志记录，不泄露敏感密钥
• 计划中的结构化 JSON 负载，便于下游自动化（参见路线图）

特性

工具

search_pixabay_images

• 必需：query（字符串）
• 可选：image_type（all|photo|illustration|vector），orientation（all|horizontal|vertical），per_page（3-200）
• 返回：当前可读文本块 + （计划）结构化 JSON 命中数组

search_pixabay_videos

• 必需：query
• 可选：video_type（all|film|animation），orientation，per_page（3-200），min_duration，max_duration
• 返回：当前可读文本块 + （计划）结构化 JSON，包括时长和 URL

配置

环境变量：

名称	必需	默认值	描述
PIXABAY_API_KEY	是	-	您的 Pixabay API 密钥（图像和视频）
PIXABAY_TIMEOUT_MS	否	10000（计划）	特性落地后请求超时时间
PIXABAY_RETRY	否	0（计划）	暂时网络错误重试次数

注意事项：

• 默认启用安全搜索。
• 密钥永远不会在结构化错误或日志中回显。

使用示例

当前（仅文本响应摘录）：

找到 120 张“猫”的图片：
- 猫，宠物，动物（用户：Alice）：https://.../medium1.jpg
- 小猫，可爱（用户：Bob）：https://.../medium2.jpg

计划中的结构化结果（路线图 v0.4+）：

{
  "content": [
    { "type": "text", "text": "找到 120 张“猫”的图片：\n- ..." },
    {
      "type": "json",
      "data": {
        "query": "cat",
        "totalHits": 120,
        "page": 1,
        "perPage": 20,
        "hits": [
          { "id": 123, "tags": ["cat","animal"], "user": "Alice", "previewURL": "...", "webformatURL": "...", "largeImageURL": "..." }
        ]
      }
    }
  ]
}

错误响应（计划中的形状）：

{
  "content": [{ "type": "text", "text": "Pixabay API 错误：400 ..." }],
  "isError": true,
  "metadata": { "status": 400, "code": "UPSTREAM_BAD_REQUEST", "hint": "检查 API 密钥或参数" }
}

开发

安装依赖：

npm install

构建服务器：

npm run build

监视模式：

npm run watch

安装

方案 1：使用 npx（推荐）

将以下内容添加到您的 Claude Desktop 配置中：

在 MacOS 上：~/Library/Application Support/Claude/claude_desktop_config.json 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pixabay-mcp": {
      "command": "npx",
      "args": ["pixabay-mcp@latest"],
      "env": {
        "PIXABAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

方案 2：本地安装

1. 克隆并构建项目：

git clone https://github.com/zym9863/pixabay-mcp.git
cd pixabay-mcp
npm install
npm run build

2. 添加服务器配置：

{
  "mcpServers": {
    "pixabay-mcp": {
      "command": "/path/to/pixabay-mcp/build/index.js",
      "env": {
        "PIXABAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

API 密钥设置

从 https://pixabay.com/api/docs/ 获取您的 Pixabay API 密钥，并将其设置在上述配置中。同一个密钥可以访问图像和视频端点。

调试

由于 MCP 服务器通过标准 I/O 通信，调试可能会很困难。我们建议使用 MCP Inspector，它作为一个包脚本可用：

npm run inspector

Inspector 将提供一个 URL，您可以在浏览器中访问调试工具。

路线图（精简版）

版本	关注点	关键事项
v0.4	结构化与可靠性	JSON 负载，超时，结构化错误
v0.5	用户体验与分页	分页/排序参数，有限重试，模块化重构，测试
v0.6	多源探索	评估整合 Unsplash/Pexels 抽象

详见 product.md 的完整待办事项及优先级。

贡献

欢迎计划中的贡献，一旦测试和模块拆分完成（目标 v0.5）。您可以自由打开问题，提出 API 形状/模式建议。

许可证

MIT

免责声明

此项目与 Pixabay 无关。请尊重 Pixabay 的服务条款和速率限制。