Skip to main content
Glama
enesjakozh
zym9863

Pixabay MCP Server

by zym9863
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

pixabay-mcp MCP Server

中文版

A Model Context Protocol (MCP) server for Pixabay image and video search with structured results & runtime validation.

This TypeScript MCP server exposes Pixabay search tools over stdio so AI assistants / agents can retrieve media safely and reliably.

Highlights:

  • Image & video search tools (Pixabay official API)

  • Runtime argument validation (enums, ranges, semantic checks)

  • Consistent error logging without leaking sensitive keys

  • Planned structured JSON payloads for easier downstream automation (see Roadmap)

Features

Tools

search_pixabay_images

  • Required: query (string)

  • Optional: image_type (all|photo|illustration|vector), orientation (all|horizontal|vertical), per_page (3-200)

  • Returns: human-readable text block (current) + (planned) structured JSON array of hits

search_pixabay_videos

  • Required: query

  • Optional: video_type (all|film|animation), orientation, per_page (3-200), min_duration, max_duration

  • Returns: human-readable text block + (planned) structured JSON with duration & URLs

Configuration

Environment variables:

Name

Required

Default

Description

PIXABAY_API_KEY

Yes

-

Your Pixabay API key (images & videos)

PIXABAY_TIMEOUT_MS

No

10000 (planned)

Request timeout once feature lands

PIXABAY_RETRY

No

0 (planned)

Number of retry attempts for transient network errors

Notes:

  • Safe search is enabled by default.

  • Keys are never echoed back in structured errors or logs.

Related MCP server: Lorem Ipsum MCP Server

Usage Examples

Current (text only response excerpt):

Found 120 images for "cat":
- cat, pet, animal (User: Alice): https://.../medium1.jpg
- kitten, cute (User: Bob): https://.../medium2.jpg

Planned structured result (Roadmap v0.4+):

{
  "content": [
    { "type": "text", "text": "Found 120 images for \"cat\":\n- ..." },
    {
      "type": "json",
      "data": {
        "query": "cat",
        "totalHits": 120,
        "page": 1,
        "perPage": 20,
        "hits": [
          { "id": 123, "tags": ["cat","animal"], "user": "Alice", "previewURL": "...", "webformatURL": "...", "largeImageURL": "..." }
        ]
      }
    }
  ]
}

Error response (planned shape):

{
  "content": [{ "type": "text", "text": "Pixabay API error: 400 ..." }],
  "isError": true,
  "metadata": { "status": 400, "code": "UPSTREAM_BAD_REQUEST", "hint": "Check API key or parameters" }
}

Development

Install dependencies:

npm install

Build the server:

npm run build

Watch mode:

npm run watch

Installation

Option 1: Using npx (Recommended)

Add this to your Claude Desktop configuration:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pixabay-mcp": {
      "command": "npx",
      "args": ["pixabay-mcp@latest"],
      "env": {
        "PIXABAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: Local Installation

  1. Clone and build the project:

git clone https://github.com/zym9863/pixabay-mcp.git
cd pixabay-mcp
npm install
npm run build

  1. Add the server config:

{
  "mcpServers": {
    "pixabay-mcp": {
      "command": "/path/to/pixabay-mcp/build/index.js",
      "env": {
        "PIXABAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

API Key Setup

Get your Pixabay API key from https://pixabay.com/api/docs/ and set it in the configuration above. The same key grants access to both image and video endpoints.

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Roadmap (Condensed)

Version

Focus

Key Items

v0.4

Structured & Reliability

JSON payload, timeout, structured errors

v0.5

UX & Pagination

page/order params, limited retry, modular refactor, tests

v0.6

Multi-source Exploration

Evaluate integrating Unsplash/Pexels abstraction

See product.md for full backlog & prioritization.

Contributing

Planned contributions welcome once tests & module split land (v0.5 target). Feel free to open issues for API shape / schema suggestions.

License

MIT

Disclaimer

This project is not affiliated with Pixabay. Respect Pixabay's Terms of Service and rate limits.

Available Tools

2 tools
search_pixabay_imagesC

Search for images on Pixabay

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query terms
image_typeNoFilter results by image typeall
orientationNoFilter results by image orientationall
per_pageNoNumber of results per page (3-200)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Search for') but doesn't describe any behavioral traits such as rate limits, authentication needs, pagination behavior, or what the response looks like. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how it operates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, making it easy to understand at a glance. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete for a search tool with 4 parameters. It doesn't cover behavioral aspects like response format, error handling, or usage constraints. While the schema handles parameters well, the overall context for proper tool invocation is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with all parameters well-documented in the schema itself. The description doesn't add any meaning beyond what the schema provides—it doesn't explain parameter interactions, default behaviors, or usage examples. This meets the baseline of 3 since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search for') and resource ('images on Pixabay'), making the purpose immediately understandable. It distinguishes from the sibling tool 'search_pixabay_videos' by specifying images, though it doesn't explicitly contrast them. The description is specific but lacks explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool 'search_pixabay_videos' or any other potential alternatives, nor does it provide context about appropriate use cases or exclusions. The user must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_pixabay_videosC

Search for videos on Pixabay

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query terms
video_typeNoFilter results by video typeall
orientationNoFilter results by video orientationall
per_pageNoNumber of results per page (3-200)
min_durationNoMinimum video duration in seconds
max_durationNoMaximum video duration in seconds

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention authentication requirements, rate limits, pagination behavior, error handling, or what the search results look like (e.g., format, fields). For a search tool with no annotations, this leaves significant gaps in understanding how it behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words, making it easy to parse and front-loaded with the core purpose. It's appropriately sized for a straightforward search tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, no annotations, no output schema), the description is incomplete. It lacks details on behavioral traits, output format, and usage context, making it insufficient for an agent to fully understand how to invoke and interpret results without relying heavily on the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no parameter-specific information beyond what's in the input schema, which has 100% coverage with detailed descriptions for all 6 parameters. Since the schema fully documents parameters, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search for') and resource ('videos on Pixabay'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling tool 'search_pixabay_images' beyond the resource type, which is implied but not stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as its sibling 'search_pixabay_images' for image searches. There's no mention of prerequisites, context, or exclusions, leaving usage entirely to inference from the tool name and parameters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0
Disambiguation5/5

The two tools have perfectly distinct purposes: one searches for images and the other searches for videos on Pixabay. There is no overlap or ambiguity between them, making it trivial for an agent to choose the correct tool based on the desired media type.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with 'search_pixabay_' as a prefix, followed by the media type ('images' or 'videos'). This naming convention is clear, predictable, and uniform across all tools in the set.

Tool Count3/5

With only two tools, the server feels thin for a media search domain, as it lacks operations for retrieving details, downloading, or managing favorites. However, it is reasonable for a minimal search-focused interface, though agents might need workarounds for extended functionality.

Completeness2/5

The tool set is severely incomplete for a Pixabay integration, covering only search operations. There are significant gaps, such as no tools for getting image/video details, downloading media, or handling user accounts, which limits agent workflows and could lead to failures in broader tasks.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Lorem Ipsum MCP Server

    ssv445
    F
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that enables image generation and retrieval from picsum.photos with customizable parameters like dimensions, filters, and output formats.
    1

  • mcp-pexels

    developer-ishan
    A
    license
    A
    quality
    C
    maintenance
    A Model Context Protocol server that exposes Pexels API tools for searching and retrieving free stock photos, videos, and curated collections, enabling AI agents to incorporate royalty-free media directly from chat.
    2
    9
    145
    2
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zym9863/pixabay-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server