What is Mcp Openverse

mcp-openverse is an MCP server that provides tools for searching and fetching openly-licensed images from Openverse, enabling users to access a wide range of images for various purposes.

Use cases

Use cases include finding images for blog posts, academic papers, marketing materials, and creative projects where copyright-free images are needed.

How to use

To use mcp-openverse, install it via npm with ‘npm install -g @mcp/openverse’ or clone the repository and build it from source. Configure it in your Claude Desktop settings to run as an MCP server.

Key features

Key features include searching for CC-licensed and public domain images, filtering by license type, source, and file format, obtaining detailed image information, finding related images, and performing essay-specific image searches.

Where to use

mcp-openverse can be used in various fields such as education, content creation, digital marketing, and any area requiring access to high-quality, openly-licensed images.

@mcp/openverse

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

Features

• 🔍 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

Installation

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

Usage

As an MCP Server

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"
      ]
    }
  }
}

Available Tools

search_images

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_image_details

Get detailed information about a specific image.

Parameters:

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

get_related_images

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_image_stats

Get statistics about available images by source.

No parameters required.

search_images_for_essay

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
}

Image Attribution

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.

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.

Development

Building from Source

npm install
npm run build

Running in Development Mode

npm run dev

Testing the Server

You can test the server using the MCP inspector:

npx @modelcontextprotocol/inspector dist/index.js

Examples

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
}

License

MIT License - see LICENSE file for details.

Contributing

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

Development Guidelines

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

Acknowledgments

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

Troubleshooting

Common Issues

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.

Debug Mode

Set the DEBUG environment variable:

DEBUG=mcp:* npx @mcp/openverse