The Pixabay MCP Server allows you to search for images on Pixabay via a Model Context Protocol server.
Search Images: Search using the
search_pixabay_imagestool with a required query stringFilter Results: Customize by image type (photo, illustration, vector), orientation (horizontal, vertical), and results per page (3-200)
Formatted Output: Receive structured results with image URLs and metadata
Configuration: Configure with a Pixabay API key and enable safe search
Error Handling: Built-in handling for API issues and invalid parameters
Provides tools for searching images on Pixabay, returning formatted results with image URLs and metadata, with options to filter by image type and orientation.
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:
queryOptional:
video_type(all|film|animation),orientation,per_page(3-200),min_duration,max_durationReturns: human-readable text block + (planned) structured JSON with duration & URLs
Configuration
Environment variables:
Name | Required | Default | Description |
| Yes | - | Your Pixabay API key (images & videos) |
| No | 10000 (planned) | Request timeout once feature lands |
| 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.
Related MCP server: mcp-pinterest
Usage Examples
Current (text only response excerpt):
Planned structured result (Roadmap v0.4+):
Error response (planned shape):
Development
Install dependencies:
Build the server:
Watch mode:
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
Option 2: Local Installation
Clone and build the project:
Add the server config:
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:
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.