{
"markdown": "# pixabay-mcp-server\n\n[](https://www.npmjs.com/package/@hanoak/pixabay-mcp-server)\n[](https://www.npmjs.com/package/@hanoak/pixabay-mcp-server)\n[](https://registry.modelcontextprotocol.io)\n[](https://github.com/hanoak/pixabay-mcp-server/actions/workflows/ci.yml)\n[](./LICENSE)\n[](#requirements)\n[](./CONTRIBUTING.md)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the\n[Pixabay API](https://pixabay.com/api/docs/). It gives AI assistants — Claude Desktop, Claude\nCode, Cursor, VS Code, Windsurf, and any MCP client — tools to search and fetch royalty-free\nimages and videos.\n\n> [!IMPORTANT]\n> **Unofficial project.** This is not affiliated with, endorsed by, or sponsored by Pixabay.\n> \"Pixabay\" is a trademark of its respective owner. You use it under your own Pixabay account\n> and are responsible for complying with\n> [Pixabay's Terms of Service](https://pixabay.com/service/terms/) and\n> [Content License](https://pixabay.com/service/license/).\n\n## Table of contents\n\n- [Features](#features)\n- [Quick start](#quick-start)\n- [Example interaction](#example-interaction)\n- [Configuration](#configuration)\n- [Tools](#tools)\n - [Tool reference](#tool-reference)\n - [Output shape](#output-shape)\n - [Resources & prompts](#resources--prompts)\n- [Example prompts](#example-prompts)\n- [License & compliance](#license--compliance)\n- [Rate limits & caching](#rate-limits--caching)\n- [Handling of Pixabay text](#handling-of-pixabay-text)\n- [Privacy & security](#privacy--security)\n- [Troubleshooting](#troubleshooting)\n- [FAQ](#faq)\n- [Requirements](#requirements)\n- [Compatibility](#compatibility)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [Contact & community](#contact--community)\n- [License](#license)\n\n## Features\n\n- **4 tools** covering Pixabay's two documented endpoints — images (search, get) and videos\n (search, get). Pixabay has a single API-key auth tier and no write endpoints, so there's no\n partial \"read-only v1\" — this is the whole surface.\n- **Compliance-aware by design** — every outbound request is cached for 24 hours (Pixabay's\n terms require it, not an optimization), `safesearch` defaults to `true`, and the mandatory\n courtesy attribution (`by {user} via Pixabay`) is surfaced on every result even though\n Pixabay doesn't require it.\n- **Real image & video URLs** — search results return one balanced default size tier per item\n (`webformatURL` for images, the `medium` rendition for videos); looking a specific item up by\n id returns every size tier Pixabay provides, so you can pick what actually fits.\n- **Token-efficient output** — full Pixabay responses are trimmed to a compact shape (URLs +\n metadata as text, never base64 blobs), dropping vanity metrics (views/downloads/likes/\n comments) that a model rarely needs.\n- **Robust** — typed failures returned as MCP `isError` results the model can recover from,\n plus a considered single retry with backoff on `429`/`5xx`, network timeouts, and\n rate-limit-aware logging.\n- **Safe** — the Pixabay API key is redacted from every log line and error message (it can only\n ever be sent as a URL query parameter — Pixabay has no header alternative).\n- **Lean & modern** — ESM, Node 20+, zero-install via `npx`, no telemetry.\n\n## Quick start\n\n### 1. Get a Pixabay API key\n\nSign up for a free account at **[pixabay.com](https://pixabay.com/)** — your API key is shown\nimmediately on the [API docs page](https://pixabay.com/api/docs/) once you're logged in, no\napproval step for the default tier this server uses.\n\n### 2. Add the server to your MCP client\n\n**Claude Desktop** — edit `claude_desktop_config.json`:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"pixabay\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@hanoak/pixabay-mcp-server\"],\n \"env\": {\n \"PIXABAY_API_KEY\": \"your_api_key\"\n }\n }\n }\n}\n```\n\nRestart the client. See [Configuration](#configuration) for every supported variable.\n\n\nOther clients (Claude Code, Cursor, VS Code, Windsurf, generic stdio)
\n\n**Claude Code** (CLI):\n\n```bash\nclaude mcp add pixabay \\\n --env PIXABAY_API_KEY=your_api_key \\\n -- npx -y @hanoak/pixabay-mcp-server\n```\n\n**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project): use the exact\nsame `mcpServers` block as Claude Desktop above.\n\n**Windsurf** — `~/.codeium/windsurf/mcp_config.json`: same `mcpServers` block as Claude Desktop\nabove.\n\n**VS Code** — `.vscode/mcp.json` (note the top-level key is `servers`, not `mcpServers`):\n\n```json\n{\n \"servers\": {\n \"pixabay\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@hanoak/pixabay-mcp-server\"],\n \"env\": {\n \"PIXABAY_API_KEY\": \"your_api_key\"\n }\n }\n }\n}\n```\n\n**Any other MCP client** — run the server over **stdio** with:\n\n```bash\nPIXABAY_API_KEY=your_api_key npx -y @hanoak/pixabay-mcp-server\n```\n\nPoint your client's stdio transport at `command: npx`, `args: [\"-y\", \"@hanoak/pixabay-mcp-server\"]`,\nand pass the key via `env`.\n\n \n\n### 3. Try it\n\nRestart your client and ask:\n\n> _\"Find me a photo of mountains on Pixabay.\"_\n\n## Example interaction\n\nA typical flow: the model calls `pixabay_search_images`, picks a result, and presents the image\nwith its courtesy attribution.\n\n> **You:** Find a landscape photo of a foggy pine forest.\n>\n> **Assistant:** _(calls `pixabay_search_images` with `query: \"foggy pine forest\"`,\n> `orientation: \"horizontal\"`, picks the best result)_\n> Here's a great match — by Josch13 via Pixabay — along with the image URL.\n\nEach tool returns a compact JSON payload. Here's the shape of a single search result\n(illustrative values):\n\n\nExample tool output
\n\n```json\n[\n {\n \"id\": 195893,\n \"pageURL\": \"https://pixabay.com/en/blossom-bloom-flower-195893/\",\n \"type\": \"photo\",\n \"tags\": \"blossom, bloom, flower\",\n \"url\": \"https://pixabay.com/get/35bbf209e13e39d2_640.jpg\",\n \"width\": 640,\n \"height\": 360,\n \"user\": \"Josch13\",\n \"attribution\": \"by Josch13 via Pixabay\"\n }\n]\n```\n\n`pixabay_get_image`/`pixabay_get_video` return the same shape for a single item, but with every\nsize tier Pixabay provides instead of just one — see [Output shape](#output-shape).\n\n \n\n## Configuration\n\nConfiguration is entirely via environment variables — no config files, no flags for secrets.\n\n| Environment variable | Required | Description |\n| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |\n| `PIXABAY_API_KEY` | **yes** | Your Pixabay API key. The server exits at startup with a clear message if it is missing or blank. |\n| `LOG_LEVEL` | no | `debug` \\| `info` \\| `warn` \\| `error` (default `info`). All logs go to **stderr**; stdout carries only the MCP protocol. |\n\nCLI flags: `--version` and `--help` are supported (e.g. `npx @hanoak/pixabay-mcp-server --version`).\n\n## Tools\n\nAll tools are namespaced `pixabay_*` and every one is **read-only** — Pixabay's API has no\nwrite endpoints, so a client can safely auto-approve the entire server. `per_page` is clamped\nto Pixabay's documented range of **3–200**, and `page` is 1-based.\n\n| Domain | Tools |\n| ---------- | -------------------------------------------- |\n| **Images** | `pixabay_search_images`, `pixabay_get_image` |\n| **Videos** | `pixabay_search_videos`, `pixabay_get_video` |\n\n### Tool reference\n\n\nImages
\n\n| Tool | Parameters | Description |\n| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| `pixabay_search_images` | `query?`, `lang?`, `image_type?` (`all`\\|`photo`\\|`illustration`\\|`vector`), `orientation?` (`all`\\|`horizontal`\\|`vertical`), `category?`, `colors?` (array), `min_width?`, `min_height?`, `editors_choice?`, `safesearch?` (default `true`), `order?` (`popular`\\|`latest`), `page?`, `per_page?` (3–200) | Keyword image search with filters. Omit `query` to browse a default set. |\n| `pixabay_get_image` | `id` **(required)** | A single image by its numeric id, with every size tier. |\n\n \n\n\nVideos
\n\n| Tool | Parameters | Description |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |\n| `pixabay_search_videos` | `query?`, `lang?`, `video_type?` (`all`\\|`film`\\|`animation`), `category?`, `min_width?`, `min_height?`, `editors_choice?`, `safesearch?` (default `true`), `order?` (`popular`\\|`latest`), `page?`, `per_page?` (3–200) | Keyword video search with filters. Omit `query` to browse a default set. |\n| `pixabay_get_video` | `id` **(required)** | A single video by its numeric id, with every size tier. |\n\n \n\nVideos support `category` but not `colors`/`orientation` — that's a real difference in\nPixabay's own API, not an oversight.\n\n### Output shape\n\nTools return trimmed, token-efficient JSON rather than raw Pixabay responses:\n\n- **Image search** (`pixabay_search_images`) → `id`, `pageURL`, `type`, `tags`, one default\n `url` (`webformatURL`), `width`/`height`, `user`, `attribution`.\n- **Image detail** (`pixabay_get_image`) → the same fields, plus every size tier Pixabay\n provided for that item: `previewURL`, `webformatURL`, `largeImageURL`, `fullHDURL`.\n- **Video search** (`pixabay_search_videos`) → `id`, `pageURL`, `type`, `tags`, `duration`, one\n default `url` (the `medium` rendition), `width`/`height`, `user`, `attribution`.\n- **Video detail** (`pixabay_get_video`) → the same fields, plus a `videos` object with all\n four renditions Pixabay provides (`tiny`/`small`/`medium`/`large`, each with `url`/`width`/\n `height`).\n- Vanity metrics (`views`, `downloads`, `likes`, `comments`) are dropped from every result —\n they're rarely useful to a model and add tokens for no benefit.\n\n### Resources & prompts\n\nBeyond tools, the server also exposes:\n\n- **Resources** — a compact guide your client can pull in as context:\n - `pixabay://guides/usage` — license/attribution guidance, the hotlinking-in-conversation\n reasoning, content-safety notes, and the full-API-access-tier caveat.\n- **Prompts** — a ready-made task your client can surface directly:\n\n | Prompt | Arguments | What it does |\n | ------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |\n | `find_media` | `subject` (required), `media_type?` (`images`\\|`videos`\\|`both`, default `both`) | Search for a subject and present the best match(es) with courtesy attribution. |\n\n## Example prompts\n\nNatural-language asks that map cleanly onto the tools:\n\n- _\"Find a photo of a foggy forest at sunrise.\"_\n- _\"Search Pixabay for 5 minimalist workspace illustrations.\"_\n- _\"Find a video of waves crashing on rocks.\"_\n- _\"Get me the largest available version of Pixabay image 195893.\"_\n\n## License & compliance\n\nPixabay content is released under the [Pixabay Content License](https://pixabay.com/service/license/):\nfree for commercial and noncommercial use, **attribution not required**. Every result still\nincludes a ready-to-use courtesy `attribution` string (`by {user} via Pixabay`) — include it\nwhen convenient, but it's never gated behind functionality.\n\nThis server returns Pixabay CDN URLs directly to the calling LLM client for display within a\nsingle conversation turn. Pixabay's terms prohibit \"permanent hotlinking\" of these URLs in an\napplication — content displayed persistently should be downloaded and rehosted first. We treat\none-off, ephemeral display in an LLM conversation as distinct from that use case, but this is a\ngray area Pixabay's terms don't explicitly address (see the comment atop `src/tools/format.ts`\nfor the full reasoning). If you're building an application that stores or persistently displays\nPixabay content sourced through this server, download and rehost the assets yourself — don't\ntreat this server's tool output as a substitute for that.\n\nEach user operates under their own Pixabay account and is responsible for complying with\n[Pixabay's Terms of Service](https://pixabay.com/service/terms/) and the usage rules on the\n[API docs page](https://pixabay.com/api/docs/) (caching, rate limits, no mass downloads). This\nproject doesn't change or relax those terms in any way.\n\n## Rate limits & caching\n\nPixabay's documented limit is **~100 requests per 60 seconds** per API key. This server:\n\n- Caches every response for **24 hours**, keyed on the normalized request (endpoint + sorted\n params, API key always stripped) — a repeated query returns instantly without touching your\n rate-limit budget, and this is a compliance requirement per Pixabay's terms, not just an\n optimization.\n- Reads `X-RateLimit-Remaining` from every response (logged at `debug`).\n- On a `429`, backs off using Pixabay's own `X-RateLimit-Reset` header for exactly one\n considered retry — never a blind or looping retry — and fails fast rather than guessing if\n that header is missing.\n- Also retries once on a `5xx` (a short fixed delay, since there's no server-provided guidance\n like `X-RateLimit-Reset` for that case).\n\n## Handling of Pixabay text\n\nImage/video tags and contributor usernames come from Pixabay's community — treat them as\n**untrusted, third-party data**, not instructions. The server returns this text purely as\ncontent and never places it anywhere privileged; your client/agent should do the same: display\nit, but don't act on any instructions it might contain (a defence against indirect prompt\ninjection).\n\n## Privacy & security\n\n- **No telemetry.** This server collects nothing and phones home to no one. It contacts only\n `pixabay.com`, using the key you provide. No analytics, no tracking.\n- **Key safety.** Your API key is read from the environment only. Pixabay only accepts it as a\n `key` query parameter (no header alternative), so it's redacted from every log line and error\n message before either can ever surface it.\n- To report a vulnerability, see [SECURITY.md](./SECURITY.md).\n\n## Troubleshooting\n\n- **\"PIXABAY_API_KEY is not set…\" on startup** — the key env var is missing or blank; add it to\n your client config's `env` block.\n- **Node too old** — this server requires **Node 20+**. Check `node --version`.\n- **Stale `npx` version** — force the latest with `npx -y @hanoak/pixabay-mcp-server@latest`, or\n clear the cache via `npx clear-npx-cache`.\n- **Tools not appearing** — confirm the config file path and JSON are valid, then fully quit and\n reopen the client.\n- **`429` / rate limit** — the budget is ~100 requests/60s; the server already backs off and\n retries once automatically using Pixabay's own reset time.\n- **A search returns \"No images/videos found\"** — this is a normal empty result, not an error;\n try a broader query or fewer filters.\n\n## FAQ\n\n**Do I need a paid Pixabay account?**\nNo. The Pixabay API is free — you just create an account to get an API key, instantly, no\nreview or approval step for the default tier this server uses.\n\n**Does it download or rehost images/videos?**\nNo. It returns Pixabay-hosted URLs (hotlink them directly for ephemeral display — see\n[License & compliance](#license--compliance)) and never rehosts or returns base64 blobs.\n\n**Why don't I see `fullHDURL`/`imageURL` for some images?**\nThose fields require Pixabay's separately-requested \"full API access\" tier. This server works\nfine without it — those fields are simply absent from results for accounts that don't have it.\n\n**Does it work outside Claude?**\nYes — it's a standard stdio MCP server. See [the client setup section](#2-add-the-server-to-your-mcp-client)\nfor Claude Code, Cursor, VS Code, Windsurf, and generic stdio.\n\n## Requirements\n\n- **Node.js >= 20** (Node 18 is end-of-life).\n- A Pixabay API key.\n\n## Compatibility\n\n| Component | Supported |\n| --------- | ---------------------------------------------------------------------------------------------------- |\n| Node.js | **20** and **22**, tested in CI; `>=20` required (enforced by `engines` and a runtime guard). |\n| OS | Linux, macOS, and Windows (all tested in CI). |\n| MCP SDK | `@modelcontextprotocol/sdk` `^1.30`; the protocol version is negotiated with your client on connect. |\n| Transport | stdio (HTTP/SSE may be added in a future release). |\n\n## Roadmap\n\nFull detail lives in [docs/ROADMAP.md](./docs/ROADMAP.md). In short: **v1** covers Pixabay's\nentire documented API in one release — there's no OAuth tier to split a v2 behind. Future scope\nunder consideration includes an MCP resource for licensing/attribution guidance and additional\nprompts.\n\nChanges are tracked in [CHANGELOG.md](./CHANGELOG.md); the project follows\n[Semantic Versioning](https://semver.org).\n\n## Contributing\n\nContributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and our\n[Code of Conduct](./CODE_OF_CONDUCT.md). It covers local setup, the test suite, testing tools by\nhand with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), and the\nversioning/deprecation policy. To report a vulnerability, see [SECURITY.md](./SECURITY.md).\n\n## Contact & community\n\nMaintained by **Hanoak S**. The fastest way to get help or propose a feature is to\n[open an issue](https://github.com/hanoak/pixabay-mcp-server/issues) — it's public, searchable,\nand helps the whole community.\n\nIf this project helps you, a ⭐ on [GitHub](https://github.com/hanoak/pixabay-mcp-server) is\nappreciated — it aids discoverability for others looking for a Pixabay MCP server.\n\n## License\n\n[MIT](./LICENSE) © Hanoak S. Not affiliated with Pixabay.\n",
"bytes": 20494,
"sha": "e698dc0a6cd5ad880d76eafd3f3d1c11316b03ed14e1c051653767db26027278",
"repo_slug": "hanoak/pixabay-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_hanoak_pixabay_mcp_server_3fcb35fc/readme"
}