Pexels Image Search MCP Server

A Model Context Protocol (MCP) server that provides image search functionality using natural language queries via the Pexels API.

Features

• 🔍 Natural Language Search: Search for images using descriptive text queries
• 🎯 Flexible Results: Control the number of results returned (1-80 images)
• 🎨 Advanced Filtering: Filter by orientation, size, color, and locale
• 📄 Pagination Support: Navigate through large result sets
• 🚀 High Performance: Async I/O for fast response times
• 🔒 Secure: API key management through environment variables
• 📝 Detailed Metadata: Get comprehensive image information including photographer details

Installation

Prerequisites

• Node.js 16.0.0 or higher
• Python 3.7 or higher
• A Pexels API key (free at pexels.com/api)

Install via npm

npm install -g pexels-image-search-mcp

Install from source

git clone <repository-url>
cd pexels_mcp
npm install
pip install -r requirements.txt

Configuration

1. Get Pexels API Key

1. Visit pexels.com/api
2. Sign up for a free account
3. Generate your API key

2. Set Environment Variable

# Linux/macOS
export PEXELS_API_KEY="your_pexels_api_key_here"

# Windows
set PEXELS_API_KEY=your_pexels_api_key_here

3. Configure MCP Client

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "pexels-image-search": {
      "command": "npx",
      "args": ["pexels-image-search-mcp@latest"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_api_key_here"
      },
      "name": "Pexels Image Search"
    }
  }
}

Other MCP Clients

{
  "servers": {
    "pexels-image-search": {
      "command": "npx",
      "args": ["pexels-image-search-mcp@latest"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_api_key_here"
      }
    }
  }
}

Usage

Basic Search

Search for images of "sunset over mountains"

Advanced Search with Parameters

Search for 5 landscape images of "ocean waves" in blue color

Available Parameters

• query (required): Natural language description of the image
• per_page (optional): Number of images to return (1-80, default: 1)
• page (optional): Page number for pagination (default: 1)
• orientation (optional): Image orientation (landscape, portrait, square)
• size (optional): Image size (large, medium, small)
• color (optional): Dominant color (red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white)
• locale (optional): Search locale (default: en-US)

Example Responses

The server returns detailed information for each image:

Found 1 image(s) for query: 'sunset over mountains'

**Image 1:**
- **ID:** 1234567
- **Photographer:** John Doe
- **Description:** Beautiful sunset over mountain peaks
- **Dimensions:** 4000 x 3000
- **Original URL:** https://images.pexels.com/photos/1234567/original.jpg
- **Large URL:** https://images.pexels.com/photos/1234567/large.jpg
- **Medium URL:** https://images.pexels.com/photos/1234567/medium.jpg
- **Small URL:** https://images.pexels.com/photos/1234567/small.jpg
- **Photographer URL:** https://www.pexels.com/@johndoe
- **Pexels URL:** https://www.pexels.com/photo/1234567/

Development

Running Locally

# Set your API key
export PEXELS_API_KEY="your_api_key_here"

# Run the server
node index.js

Testing

# Run tests
npm test

# Test Python components
python -m pytest test_pexels_image_search.py

Project Structure

pexels_mcp/
├── package.json              # npm package configuration
├── pexels_image_search.py   # Main MCP server implementation
├── bin/pexels-image-search-mcp  # Executable script
├── index.js                 # Node.js entry point
├── requirements.txt         # Python dependencies
├── README.md               # This file
└── test/                   # Test files
    ├── test_pexels_image_search.py
    └── test-npm-package.js

API Limits

• Free Tier: 200 requests per hour
• Rate Limiting: Automatic handling with appropriate error messages
• Image Sizes: Multiple resolutions available for each image

Troubleshooting

Common Issues

1. "Invalid Pexels API key" Error

   • Verify your API key is correct
   • Ensure the environment variable is set properly
   • Check that your API key hasn't expired

2. "Rate limit exceeded" Error

   • Wait before making more requests
   • Consider upgrading your Pexels plan for higher limits

3. "Connection closed" Error

   • Check your internet connection
   • Verify the MCP client configuration
   • Restart the MCP server

4. Python Dependencies Missing

   • Run pip install -r requirements.txt
   • Ensure Python 3.7+ is installed

Debug Mode

Enable debug logging by setting the environment variable:

export PYTHONPATH="."
export MCP_LOG_LEVEL="DEBUG"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the troubleshooting section
• Review Pexels API documentation

Acknowledgments

• Pexels for providing the image search API
• Model Context Protocol for the MCP specification
• All the talented photographers on Pexels