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
- Clone and build the project:
git clone https://github.com/zym9863/pixabay-mcp.git
cd pixabay-mcp
npm install
npm run build
- 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.