pixabay-mcp MCP Server

中文版

A Model Context Protocol (MCP) server for Pixabay image and video search with structured results & runtime validation.

This TypeScript MCP server exposes Pixabay search tools over stdio so AI assistants / agents can retrieve media safely and reliably.

Highlights:

• Image & video search tools (Pixabay official API)
• Runtime argument validation (enums, ranges, semantic checks)
• Consistent error logging without leaking sensitive keys
• Planned structured JSON payloads for easier downstream automation (see Roadmap)

Features

Tools

search_pixabay_images

• Required: query (string)
• Optional: image_type (all|photo|illustration|vector), orientation (all|horizontal|vertical), per_page (3-200)
• Returns: human-readable text block (current) + (planned) structured JSON array of hits

search_pixabay_videos

• Required: query
• Optional: video_type (all|film|animation), orientation, per_page (3-200), min_duration, max_duration
• Returns: human-readable text block + (planned) structured JSON with duration & URLs

Configuration

Environment variables:

Notes:

• Safe search is enabled by default.
• Keys are never echoed back in structured errors or logs.

Usage Examples

Current (text only response excerpt):

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

Planned structured result (Roadmap 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": "..." }
        ]
      }
    }
  ]
}

Error response (planned shape):

{
  "content": [{ "type": "text", "text": "Pixabay API error: 400 ..." }],
  "isError": true,
  "metadata": { "status": 400, "code": "UPSTREAM_BAD_REQUEST", "hint": "Check API key or parameters" }
}

Development

Install dependencies:

npm install

Build the server:

npm run build

Watch mode:

npm run watch

Installation

Option 1: Using npx (Recommended)

Add this to your Claude Desktop configuration: