pixabay-mcp-server

A Model Context Protocol (MCP) server for the Pixabay API. It gives AI assistants — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and any MCP client — tools to search and fetch royalty-free images and videos.

[!IMPORTANT] Unofficial project. This is not affiliated with, endorsed by, or sponsored by Pixabay. "Pixabay" is a trademark of its respective owner. You use it under your own Pixabay account and are responsible for complying with Pixabay's Terms of Service and Content License.

Table of contents

• Features
• Quick start
• Example interaction
• Configuration
• Tools
  • Tool reference
  • Output shape
  • Resources & prompts
• Example prompts
• License & compliance
• Rate limits & caching
• Handling of Pixabay text
• Privacy & security
• Troubleshooting
• FAQ
• Requirements
• Compatibility
• Roadmap
• Contributing
• Contact & community
• License

Features

• 4 tools covering Pixabay's two documented endpoints — images (search, get) and videos (search, get). Pixabay has a single API-key auth tier and no write endpoints, so there's no partial "read-only v1" — this is the whole surface.
• Compliance-aware by design — every outbound request is cached for 24 hours (Pixabay's terms require it, not an optimization), safesearch defaults to true, and the mandatory courtesy attribution (by {user} via Pixabay) is surfaced on every result even though Pixabay doesn't require it.
• Real image & video URLs — search results return one balanced default size tier per item (webformatURL for images, the medium rendition for videos); looking a specific item up by id returns every size tier Pixabay provides, so you can pick what actually fits.
• Token-efficient output — full Pixabay responses are trimmed to a compact shape (URLs + metadata as text, never base64 blobs), dropping vanity metrics (views/downloads/likes/ comments) that a model rarely needs.
• Robust — typed failures returned as MCP isError results the model can recover from, plus a considered single retry with backoff on 429/5xx, network timeouts, and rate-limit-aware logging.
• Safe — the Pixabay API key is redacted from every log line and error message (it can only ever be sent as a URL query parameter — Pixabay has no header alternative).
• Lean & modern — ESM, Node 20+, zero-install via npx, no telemetry.

Quick start

1. Get a Pixabay API key

Sign up for a free account at pixabay.com — your API key is shown immediately on the API docs page once you're logged in, no approval step for the default tier this server uses.

2. Add the server to your MCP client

Claude Desktop — edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "pixabay": {
      "command": "npx",
      "args": ["-y", "@hanoak/pixabay-mcp-server"],
      "env": {
        "PIXABAY_API_KEY": "your_api_key"
      }
    }
  }
}

Restart the client. See Configuration for every supported variable.

claude mcp add pixabay \
  --env PIXABAY_API_KEY=your_api_key \
  -- npx -y @hanoak/pixabay-mcp-server

{
  "servers": {
    "pixabay": {
      "command": "npx",
      "args": ["-y", "@hanoak/pixabay-mcp-server"],
      "env": {
        "PIXABAY_API_KEY": "your_api_key"
      }
    }
  }
}

PIXABAY_API_KEY=your_api_key npx -y @hanoak/pixabay-mcp-server

3. Try it

Restart your client and ask:

"Find me a photo of mountains on Pixabay."

Example interaction

A typical flow: the model calls pixabay_search_images, picks a result, and presents the image with its courtesy attribution.

You: Find a landscape photo of a foggy pine forest.

Assistant: (calls pixabay_search_images with query: "foggy pine forest", orientation: "horizontal", picks the best result) Here's a great match — by Josch13 via Pixabay — along with the image URL.

Each tool returns a compact JSON payload. Here's the shape of a single search result (illustrative values):

[
  {
    "id": 195893,
    "pageURL": "https://pixabay.com/en/blossom-bloom-flower-195893/",
    "type": "photo",
    "tags": "blossom, bloom, flower",
    "url": "https://pixabay.com/get/35bbf209e13e39d2_640.jpg",
    "width": 640,
    "height": 360,
    "user": "Josch13",
    "attribution": "by Josch13 via Pixabay"
  }
]

Configuration

Configuration is entirely via environment variables — no config files, no flags for secrets.

CLI flags: --version and --help are supported (e.g. npx @hanoak/pixabay-mcp-server --version).

Tools

All tools are namespaced pixabay_* and every one is read-only — Pixabay's API has no write endpoints, so a client can safely auto-approve the entire server. per_page is clamped to Pixabay's documented range of 3–200, and page is 1-based.

Tool reference