Pixabay MCP Server

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](https://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.

Other clients (Claude Code, Cursor, VS Code, Windsurf, generic stdio)

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):

Example tool output

[

{ "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

Images

Videos

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,