Skip to main content
Glama

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

Related MCP server: Pixabay MCP Server

Installation

  1. Clone this repository:

git clone <your-repo-url>
cd pixabay-mcp-server
  1. Install dependencies:

npm install
  1. 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

Search for "mountain landscape" photos
Search for horizontal nature photos with minimum width 1920px, editors choice only
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.

Available Tools

4 tools
get_image_by_idB

Retrieve a specific image by its Pixabay ID

Inputs: id (required).

get_video_by_idB

Retrieve a specific video by its Pixabay ID

Inputs: id (required).

search_imagesC

Search for royalty-free images on Pixabay

Inputs: q, lang, image_type, orientation, +9 more.

search_videosC

Search for royalty-free videos on Pixabay

Inputs: q, lang, video_type, category, +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity: two tools retrieve specific media by ID (image vs. video), and two tools search for media (images vs. videos). The resource type (image/video) and action (get/search) are consistently differentiated, making misselection unlikely.

    Naming Consistency5/5

    Tool names follow a perfect verb_noun pattern throughout: all use snake_case with consistent verbs ('get' for retrieval, 'search' for searching) and clear nouns ('image_by_id', 'video_by_id', 'images', 'videos'). There are no deviations or mixed conventions.

    Tool Count5/5

    With 4 tools, this server is well-scoped for its Pixabay media retrieval purpose. Each tool earns its place by covering essential operations: retrieval and search for both images and videos, which is appropriate and not overly complex or thin.

    Completeness5/5

    The tool surface is complete for the domain of accessing Pixabay media. It provides full coverage for both images and videos with retrieval (get) and discovery (search) operations, leaving no obvious gaps or dead ends for an agent working with this API.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and retrieving high-quality stock photos from Pexels with advanced filtering options including orientation, size, color, and localization support.
      33 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and retrieving free photos and videos from Pexels using natural language queries, with support for filters like orientation, size, color, and duration.
      33 npm
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search and retrieve Pexels photos, videos, and collections, including curated and popular media, with filtering by orientation, size, color, locale, and duration. Also supports fetching individual photos, videos, and collection media through the Pexels API.
      92 npm
      MIT