Pixabay MCP

Pixabay-MCP MCP服务器

中文版

一个用于Pixabay图片和视频搜索的模型上下文协议（MCP）服务器，提供结构化结果及运行时验证。

这个TypeScript MCP服务器通过stdio暴露Pixabay搜索工具，以便AI助手/代理能够安全可靠地检索媒体。

亮点：

• 图片和视频搜索工具（Pixabay官方API）
• 运行时参数验证（枚举、范围、语义检查）
• 持续记录错误日志而不泄露敏感密钥
• 计划设计结构化的JSON数据负载，以简化下游自动化流程（参见路线图）

特点/功能

工具

search_pixabay_images

• 要求： query (字符串)
• 可选： image_type (全部|照片|插图|矢量图)， orientation （全部|水平|垂直）， per_page (3-200)
• 返回：人类可读的文本块（当前）+ （计划中的）结构化JSON数组的命中结果

search_pixabay_videos

• 要求： query
• 可选： video_type （全部|电影|动画）， orientation， per_page (3-200) min_duration， max_duration
• 返回：可读的人类文本块 + （计划中的）包含持续时间和URL的结构化JSON

配置

环境变量： | 名称 | 必填 | 默认值 | 描述 | | ---- | -------- | ------- | ----------- | （表格分隔线，无实际翻译内容） | PIXABAY_API_KEY 是 | - | 您的Pixabay API密钥（图片和视频） | | PIXABAY_TIMEOUT_MS | 编号 | 10000（计划中） | 功能上线后请求超时 | | PIXABAY_RETRY | 编号 | 0（计划中） | 临时网络错误的重试次数 |

注：

• 安全搜索功能默认已开启。
• 在结构化错误或日志中，密钥永远不会被回显。

使用示例

当前（仅文本回复摘录）：

Found 120 images for "cat":
- cat, pet, animal (User: Alice): https://.../medium1.jpg
- kitten, cute (User: Bob): https://.../medium2.jpg

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

{
  "content": [
    { "type": "text", "text": "Found 120 images for \"cat\":\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 error: 400 ..." }],
  "isError": true,
  "metadata": { "status": 400, "code": "UPSTREAM_BAD_REQUEST", "hint": "Check API key or parameters" }
}

发展

安装依赖项：

npm install

构建服务器：

npm run build

观看模式：

npm run watch

安装

选项1：使用npx（推荐）

将此添加到您的Claude桌面配置中：

在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

1. 添加服务器配置：

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

API密钥设置

从以下位置获取您的Pixabay API密钥： https://pixabay.com/api/docs/ 的中文翻译为：“https://pixabay.com 的 API 文档/” 并在上述配置中进行设置。相同的密钥可用于访问图像和视频端点。

调试

由于MCP服务器通过标准输入输出进行通信，因此调试可能会具有挑战性。我们建议使用 MCP检查器，这可以作为一个包脚本使用：

npm run inspector

检查员将提供一个URL，以便您在浏览器中访问调试工具。

路线图（精简版）

见 product.md 以处理全部积压任务并确定优先级。

做出贡献

欢迎在测试和模块拆分完成后（目标版本v0.5）提出计划中的贡献。如需对API结构/模式提出建议，请随时提交问题。

许可证

麻省理工学院（MIT）

免责声明

此项目与Pixabay无任何关联。请遵守Pixabay的服务条款和速率限制。