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.

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

Related MCP server: UnSplashX

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 Code (CLI):

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

Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project): use the exact same mcpServers block as Claude Desktop above.

Windsurf — ~/.codeium/windsurf/mcp_config.json: same mcpServers block as Claude Desktop above.

VS Code — .vscode/mcp.json (note the top-level key is servers, not mcpServers):

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

Any other MCP client — run the server over stdio with:

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

Point your client's stdio transport at command: npx, args: ["-y", "@hanoak/pixabay-mcp-server"], and pass the key via env.

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"
  }
]

pixabay_get_image/pixabay_get_video return the same shape for a single item, but with every size tier Pixabay provides instead of just one — see Output shape.

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

Videos support category but not colors/orientation — that's a real difference in Pixabay's own API, not an oversight.

Output shape

Tools return trimmed, token-efficient JSON rather than raw Pixabay responses:

• Image search (pixabay_search_images) → id, pageURL, type, tags, one default url (webformatURL), width/height, user, attribution.

• Image detail (pixabay_get_image) → the same fields, plus every size tier Pixabay provided for that item: previewURL, webformatURL, largeImageURL, fullHDURL.

• Video search (pixabay_search_videos) → id, pageURL, type, tags, duration, one default url (the medium rendition), width/height, user, attribution.

• Video detail (pixabay_get_video) → the same fields, plus a videos object with all four renditions Pixabay provides (tiny/small/medium/large, each with url/width/ height).

• Vanity metrics (views, downloads, likes, comments) are dropped from every result — they're rarely useful to a model and add tokens for no benefit.

Resources & prompts

Beyond tools, the server also exposes:

• Resources — a compact guide your client can pull in as context:

  • pixabay://guides/usage — license/attribution guidance, the hotlinking-in-conversation reasoning, content-safety notes, and the full-API-access-tier caveat.

• Prompts — a ready-made task your client can surface directly:

  Prompt	Arguments	What it does
  find_media	subject (required), media_type? (images|videos|both, default both)	Search for a subject and present the best match(es) with courtesy attribution.

Example prompts

Natural-language asks that map cleanly onto the tools:

• "Find a photo of a foggy forest at sunrise."

• "Search Pixabay for 5 minimalist workspace illustrations."

• "Find a video of waves crashing on rocks."

• "Get me the largest available version of Pixabay image 195893."

License & compliance

Pixabay content is released under the Pixabay Content License: free for commercial and noncommercial use, attribution not required. Every result still includes a ready-to-use courtesy attribution string (by {user} via Pixabay) — include it when convenient, but it's never gated behind functionality.

This server returns Pixabay CDN URLs directly to the calling LLM client for display within a single conversation turn. Pixabay's terms prohibit "permanent hotlinking" of these URLs in an application — content displayed persistently should be downloaded and rehosted first. We treat one-off, ephemeral display in an LLM conversation as distinct from that use case, but this is a gray area Pixabay's terms don't explicitly address (see the comment atop src/tools/format.ts for the full reasoning). If you're building an application that stores or persistently displays Pixabay content sourced through this server, download and rehost the assets yourself — don't treat this server's tool output as a substitute for that.

Each user operates under their own Pixabay account and is responsible for complying with Pixabay's Terms of Service and the usage rules on the API docs page (caching, rate limits, no mass downloads). This project doesn't change or relax those terms in any way.

Rate limits & caching

Pixabay's documented limit is ~100 requests per 60 seconds per API key. This server:

• Caches every response for 24 hours, keyed on the normalized request (endpoint + sorted params, API key always stripped) — a repeated query returns instantly without touching your rate-limit budget, and this is a compliance requirement per Pixabay's terms, not just an optimization.

• Reads X-RateLimit-Remaining from every response (logged at debug).

• On a 429, backs off using Pixabay's own X-RateLimit-Reset header for exactly one considered retry — never a blind or looping retry — and fails fast rather than guessing if that header is missing.

• Also retries once on a 5xx (a short fixed delay, since there's no server-provided guidance like X-RateLimit-Reset for that case).

Handling of Pixabay text

Image/video tags and contributor usernames come from Pixabay's community — treat them as untrusted, third-party data, not instructions. The server returns this text purely as content and never places it anywhere privileged; your client/agent should do the same: display it, but don't act on any instructions it might contain (a defence against indirect prompt injection).

Privacy & security

• No telemetry. This server collects nothing and phones home to no one. It contacts only pixabay.com, using the key you provide. No analytics, no tracking.

• Key safety. Your API key is read from the environment only. Pixabay only accepts it as a key query parameter (no header alternative), so it's redacted from every log line and error message before either can ever surface it.

• To report a vulnerability, see SECURITY.md.

Troubleshooting

• "PIXABAY_API_KEY is not set…" on startup — the key env var is missing or blank; add it to your client config's env block.

• Node too old — this server requires Node 20+. Check node --version.

• Stale npx version — force the latest with npx -y @hanoak/pixabay-mcp-server@latest, or clear the cache via npx clear-npx-cache.

• Tools not appearing — confirm the config file path and JSON are valid, then fully quit and reopen the client.

• 429 / rate limit — the budget is ~100 requests/60s; the server already backs off and retries once automatically using Pixabay's own reset time.

• A search returns "No images/videos found" — this is a normal empty result, not an error; try a broader query or fewer filters.

FAQ

Do I need a paid Pixabay account? No. The Pixabay API is free — you just create an account to get an API key, instantly, no review or approval step for the default tier this server uses.

Does it download or rehost images/videos? No. It returns Pixabay-hosted URLs (hotlink them directly for ephemeral display — see License & compliance) and never rehosts or returns base64 blobs.

Why don't I see fullHDURL/imageURL for some images? Those fields require Pixabay's separately-requested "full API access" tier. This server works fine without it — those fields are simply absent from results for accounts that don't have it.

Does it work outside Claude? Yes — it's a standard stdio MCP server. See the client setup section for Claude Code, Cursor, VS Code, Windsurf, and generic stdio.

Requirements

• Node.js >= 20 (Node 18 is end-of-life).

• A Pixabay API key.

Compatibility

Roadmap

Full detail lives in docs/ROADMAP.md. In short: v1 covers Pixabay's entire documented API in one release — there's no OAuth tier to split a v2 behind. Future scope under consideration includes an MCP resource for licensing/attribution guidance and additional prompts.

Changes are tracked in CHANGELOG.md; the project follows Semantic Versioning.

Contributing

Contributions are welcome — see CONTRIBUTING.md and our Code of Conduct. It covers local setup, the test suite, testing tools by hand with the MCP Inspector, and the versioning/deprecation policy. To report a vulnerability, see SECURITY.md.

Contact & community

Maintained by Hanoak S. The fastest way to get help or propose a feature is to open an issue — it's public, searchable, and helps the whole community.

If this project helps you, a ⭐ on GitHub is appreciated — it aids discoverability for others looking for a Pixabay MCP server.

License

MIT © Hanoak S. Not affiliated with Pixabay.