Openverse MCP server for AI agents

The MCP/Openverse server provides tools for searching and fetching openly-licensed images from Openverse. It allows you to search for Creative Commons-licensed and public domain images with various filters, get detailed image information, find related images, and even perform essay-specific image searches.

Installation

You can install the MCP/Openverse server using npm:

npm install -g @mcp/openverse

Alternatively, you can install from source:

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

Configuration

Setting up with Claude Desktop

Add the MCP/Openverse server to your Claude Desktop configuration by editing the claude_desktop_config.json file located at ~/Library/Application Support/Claude/claude_desktop_config.json:

For npm-installed version:

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

For locally-installed version:

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

Available Tools

Searching for Images

Use the search_images tool to find 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"
}

Getting Image Details

Use the get_image_details tool to retrieve detailed information about a specific image:

Parameters:

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

Finding Related Images

Use the get_related_images tool to 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)

Getting Image Statistics

Use the get_image_stats tool to get statistics about available images by source. No parameters required.

Searching Images for Essays

Use the search_images_for_essay 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
}

Image Attribution

All images from Openverse have 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.

Rate Limits

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.

Example Use Cases

Finding Images for a Blog Post

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

Searching with Specific Requirements

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

Troubleshooting

Common Issues

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

Debug Mode

You can enable debug mode by setting the DEBUG environment variable:

DEBUG=mcp:* npx @mcp/openverse

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "openverse" '{"command":"npx","args":["@mcp/openverse"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect