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:

Name	Required	Default	Description
PIXABAY_API_KEY	Yes	-	Your Pixabay API key (images & videos)
PIXABAY_TIMEOUT_MS	No	10000 (planned)	Request timeout once feature lands
PIXABAY_RETRY	No	0 (planned)	Number of retry attempts for transient network errors

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:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Option 2: Local Installation

1. Clone and build the project:

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

2. Add the server config:

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

API Key Setup

Get your Pixabay API key from https://pixabay.com/api/docs/ and set it in the configuration above. The same key grants access to both image and video endpoints.

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Roadmap (Condensed)

Version	Focus	Key Items
v0.4	Structured & Reliability	JSON payload, timeout, structured errors
v0.5	UX & Pagination	page/order params, limited retry, modular refactor, tests
v0.6	Multi-source Exploration	Evaluate integrating Unsplash/Pexels abstraction

See product.md for full backlog & prioritization.

Contributing

Planned contributions welcome once tests & module split land (v0.5 target). Feel free to open issues for API shape / schema suggestions.

License

MIT

Disclaimer

This project is not affiliated with Pixabay. Respect Pixabay's Terms of Service and rate limits.