@mcp/openverse

一个MCP（模型上下文协议）服务器，提供工具用于搜索和获取来自Openverse的公开许可图像。

功能

• 🔍 搜索CC许可和公共领域图像
• 🎨 根据许可类型、来源、文件格式等进行筛选
• 📊 获取详细的图像信息，包括归属信息
• 🔗 查找相关图像
• 📝 针对文章内容插图的特定图像搜索
• ⚡ 使用TypeScript和fastmcp构建，性能优秀

安装

npm install -g @mcp/openverse

或者从源码安装：

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

使用方法

作为MCP服务器

添加到你的Claude Desktop配置中（~/Library/Application Support/Claude/claude_desktop_config.json）：

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

或者如果本地安装：

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

可用工具

search_images

根据各种过滤器搜索公开许可的图像。

参数：

• query（必需）：搜索词
• page：页数（默认：1）
• page_size：每页结果数量（默认：20，最大：500）
• license：许可类型（by，by-sa，by-nc，by-nd，cc0等）
• license_type：commercial或modification
• creator：按创作者名称筛选
• source：按来源筛选（flickr，wikimedia，met等）
• extension：文件类型（jpg，png，gif，svg）
• aspect_ratio：tall，wide或square
• size：small，medium或large
• mature：是否包含成熟内容（默认：false）

示例：

// 搜索具有商业许可的森林景观照片
{
  "query": "forest landscape",
  "page_size": 10,
  "license_type": "commercial",
  7"extension": "jpg",
  "aspect_ratio": "wide"
}

get_image_details

获取特定图像的详细信息。

参数：

• image_id（必需）：Openverse图像ID（UUID格式）

get_related_images

查找与特定图像相关的图像。

参数：

• image_id（必需）：要查找相关图像的图像ID
• page：页数（默认：1）
• page_size：每页结果数量（默认：10）

get_image_stats

获取按来源分类的可用图像统计数据。

无需参数。

search_images_for_essay

高级工具，用于查找插图以说明文章或文章。

参数：

• essay_topic（必需）：文章的主要主题/标题
• concepts（必需）：要查找图像的关键概念数组
• style：photo，illustration或any（默认：any）
• max_images：返回的最大图像数量（默认：10）

示例：

{
  "essay_topic": "气候变化",
  "concepts": ["全球变暖", "可再生能源", "碳排放"],
  "style": "photo",
  "max_images": 15
}

图像归属

来自Openverse的所有图像都附有归属要求。API提供：

• attribution：预格式化的归属文本
• license：许可代码（例如，'by-sa'）
• license_url：许可链接
• creator：原始创作者/摄影师
• creator_url：创作者个人资料链接

在使用图像时，请始终包含适当的归属。

请求限制

Openverse API具有以下请求限制：

• 匿名：每天100次请求，每小时5次请求
• 认证：每天10,000次请求，每分钟100次请求

此MCP服务器当前使用匿名访问。如需更高的请求限制，请考虑实现OAuth认证。

开发

从源码构建

npm install
npm run build

在开发模式下运行

npm run dev

测试服务器

你可以使用MCP检查器测试服务器：

npx @modelcontextprotocol/inspector dist/index.js

示例

为博客文章查找图像

// 使用search_images_for_essay工具
{
  "essay_topic": "可持续建筑",
  "concepts": ["绿色建筑", "太阳能板", "环保设计"],
  "style": "photo",
  "max_images": 10
}

具有特定需求的搜索

// 使用search_images工具
{
  "query": "山景日出",
  "aspect_ratio": "wide",
  "license_type": "commercial",
  "extension": "jpg",
  "size": "large",
  "page_size": 20
}

许可

MIT许可 - 详情见LICENSE文件。

贡献

欢迎贡献！请随意提交Pull Request。

开发指南

1. 遵循TypeScript最佳实践
2. 为新功能添加测试
3. 更新文档
4. 确保所有工具都有适当的错误处理

致谢

• Openverse 提供API和公开许可的内容
• WordPress 维护Openverse项目
• fastmcp 提供优秀的MCP框架

故障排除

常见问题

1. 请求限制错误：您已达到匿名API限制。等待一小时或实现认证。
2. 没有结果：尝试更广泛的搜索词或移除筛选条件。
3. 连接错误：检查您的互联网连接和防火墙设置。

调试模式

设置DEBUG环境变量：

DEBUG=mcp:* npx @mcp/openverse