An MCP (Model Context Protocol) server that provides tools for searching and fetching openly-licensed images from Openverse.

• 🔍 Search for CC-licensed and public domain images
• 🎨 Filter by license type, source, file format, and more
• 📊 Get detailed image information including attribution
• 🔗 Find related images
• 📝 Essay-specific image search for content illustration
• ⚡ Built with TypeScript and fastmcp for excellent performance

npm install -g @mcp/openverse

Or install from source:

git clone https://github.com/yourusername/mcp-openverse.git
cd mcp-openverse
npm install
npm run build
npm link

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "openverse": {
      "command": "npx",
      "args": ["@mcp/openverse"]
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "openverse": {
      "command": "node",
      "args": ["/path/to/mcp-openverse/dist/index.js"]
    }
  }
}

Search for openly-licensed images with various filters.

Parameters:

• query (required): Search terms
• page: Page number (default: 1)
• page_size: Results per page (default: 20, max: 500)
• license: License type (by, by-sa, by-nc, by-nd, cc0, etc.)
• license_type: commercial or modification
• creator: Filter by creator name
• source: Filter by source (flickr, wikimedia, met, etc.)
• extension: File type (jpg, png, gif, svg)
• aspect_ratio: tall, wide, or square
• size: small, medium, or large
• mature: Include mature content (default: false)

Example:

// Search for nature photos with commercial license
{
  "query": "forest landscape",
  "page_size": 10,
  "license_type": "commercial",
  "extension": "jpg",
  "aspect_ratio": "wide"
}

Get detailed information about a specific image.

Parameters:

• image_id (required): Openverse image ID (UUID format)

Find images related to a specific image.

Parameters:

• image_id (required): The image ID to find related images for
• page: Page number (default: 1)
• page_size: Results per page (default: 10)

Get statistics about available images by source.

No parameters required.

High-level tool for finding images to illustrate essays or articles.

Parameters:

• essay_topic (required): Main topic/title of the essay
• concepts (required): Array of key concepts to find images for
• style: photo, illustration, or any (default: any)
• max_images: Maximum images to return (default: 10)

Example:

{
  "essay_topic": "Climate Change",
  "concepts": ["global warming", "renewable energy", "carbon emissions"],
  "style": "photo",
  "max_images": 15
}

All images from Openverse come with attribution requirements. The API provides:

• attribution: Pre-formatted attribution text
• license: License code (e.g., 'by-sa')
• license_url: Link to the license
• creator: Original creator/photographer
• creator_url: Link to creator's profile

Always include proper attribution when using images.

The Openverse API has the following rate limits:

• Anonymous: 100 requests/day, 5 requests/hour
• Authenticated: 10,000 requests/day, 100 requests/minute

This MCP server currently uses anonymous access. For higher rate limits, consider implementing OAuth authentication.

npm install
npm run build

npm run dev

You can test the server using the MCP inspector:

npx @modelcontextprotocol/inspector dist/index.js

// Using the search_images_for_essay tool
{
  "essay_topic": "Sustainable Architecture",
  "concepts": ["green building", "solar panels", "eco-friendly design"],
  "style": "photo",
  "max_images": 10
}

// Using the search_images tool
{
  "query": "mountain landscape sunrise",
  "aspect_ratio": "wide",
  "license_type": "commercial",
  "extension": "jpg",
  "size": "large",
  "page_size": 20
}

MIT License - see LICENSE file for details.

Contributions are welcome! Please feel free to submit a Pull Request.

1. Follow TypeScript best practices
2. Add tests for new features
3. Update documentation
4. Ensure all tools have proper error handling

• Openverse for providing the API and openly-licensed content
• WordPress for maintaining the Openverse project
• fastmcp for the excellent MCP framework

1. Rate limit errors: You're hitting the anonymous API limits. Wait an hour or implement authentication.
2. No results: Try broader search terms or remove filters.
3. Connection errors: Check your internet connection and firewall settings.

Set the DEBUG environment variable:

DEBUG=mcp:* npx @mcp/openverse