MCP Openverse

🚀 @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

Install via npm

npm install -g @mcp/openverse

Install from source

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

💻 Usage Examples

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.

Parameters: None

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
}

📚 Documentation

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.

🔧 Technical Details

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

💻 Usage 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