Unlock-MCP/pixabay-mcp-server

Pixabay MCP Server

A Model Context Protocol (MCP) server that provides access to the Pixabay API for searching and retrieving royalty-free images and videos.

📖 Complete Setup and Usage Guide - Step-by-step tutorial with examples and troubleshooting

Features

• Image Search: Search through millions of royalty-free images
• Video Search: Find high-quality stock videos
• Advanced Filtering: Filter by category, orientation, color, size, and more
• Individual Lookup: Get specific images or videos by ID
• Multiple Formats: Access different image sizes and video qualities

Installation

1. Clone this repository:

git clone <your-repo-url>
cd pixabay-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

API Key Setup

You'll need a Pixabay API key to use this server:

1. Sign up at Pixabay
2. Go to Pixabay API page
3. Get your API key
4. Set the system environment variable (recommended for security):

For bash/zsh (add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile):

export PIXABAY_API_KEY="your-api-key-here"

For fish (add to ~/.config/fish/config.fish):

set -gx PIXABAY_API_KEY "your-api-key-here"

For Windows (Command Prompt):

setx PIXABAY_API_KEY "your-api-key-here"

After setting the environment variable, restart your terminal or run:

source ~/.zshrc  # or your shell's config file

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Recommended (using system environment variable):

{
  "mcpServers": {
    "pixabay": {
      "command": "node",
      "args": ["/path/to/pixabay-mcp-server/dist/index.js"]
    }
  }
}

Alternative (less secure - API key in config file):

{
  "mcpServers": {
    "pixabay": {
      "command": "node",
      "args": ["/path/to/pixabay-mcp-server/dist/index.js"],
      "env": {
        "PIXABAY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Security Note: The recommended approach uses your system environment variable, keeping the API key out of configuration files.

Available Tools

search_images

Search for royalty-free images with various filters:

• q: Search term (max 100 characters)
• lang: Language code (default: "en")
• image_type: "all", "photo", "illustration", "vector"
• orientation: "all", "horizontal", "vertical"
• category: Category filter (nature, business, etc.)
• min_width/min_height: Minimum dimensions
• colors: Color filter (red, blue, grayscale, etc.)
• editors_choice: Editor's Choice awards only
• safesearch: Safe for all ages
• order: "popular" or "latest"
• page: Page number (default: 1)
• per_page: Results per page (3-200, default: 20)

search_videos

Search for royalty-free videos with similar filtering options:

• q: Search term
• video_type: "all", "film", "animation"
• All other parameters similar to image search

get_image_by_id

Retrieve a specific image by its Pixabay ID:

• id: Pixabay image ID (required)

get_video_by_id

Retrieve a specific video by its Pixabay ID:

• id: Pixabay video ID (required)

Usage Examples

Basic Image Search

Search for "mountain landscape" photos

Advanced Image Search

Search for horizontal nature photos with minimum width 1920px, editors choice only

Video Search

Find animation videos about "space exploration"

API Rate Limits

• 100 requests per 60 seconds by default
• Responses must be cached for 24 hours
• Systematic mass downloads are not allowed

Response Format

The server returns JSON responses with image/video metadata including:

• URLs for different sizes
• Dimensions and file sizes
• View/download/like counts
• User information
• Tags and categories

Development

Running in Development Mode

npm run dev

Building

npm run build

Testing

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Author

Created by UnlockMCP - Your guide to mastering Model Context Protocol implementations.

License

MIT License - see LICENSE file for details

Disclaimer

This server provides access to Pixabay's API. Please comply with:

• Pixabay's Terms of Service
• Content License requirements
• Attribution requirements when displaying search results
• Rate limiting and caching requirements

Images and videos are subject to Pixabay's Content License. Always check individual image/video licenses before use.