mcp-openverse

🚀 @mcp/openverse

@mcp/openverse 是一个 MCP（模型上下文协议）服务器，它提供了从 Openverse 搜索和获取开放许可图像的工具。借助该服务器，用户能够轻松地找到符合各种需求的开放许可图像。

🚀 快速开始

你可以通过以下步骤快速使用 @mcp/openverse 服务器：

1. 安装服务器（具体安装方式见“📦 安装指南”）。
2. 配置 Claude Desktop（具体配置方式见“💻 使用示例”）。
3. 开始使用服务器提供的工具进行图像搜索和获取。

✨ 主要特性

• 🔍 搜索知识共享许可（CC）和公共领域的图像。
• 🎨 可以按许可类型、来源、文件格式等进行过滤。
• 📊 获取包含版权声明的详细图像信息。
• 🔗 查找相关图像。
• 📝 针对文章内容进行特定的图像搜索，用于内容配图。
• ⚡ 使用 TypeScript 和 fastmcp 构建，性能卓越。

📦 安装指南

你可以通过以下两种方式安装 @mcp/openverse：

使用 npm 全局安装

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",
  "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": "Climate Change",
  "concepts": ["global warming", "renewable energy", "carbon emissions"],
  "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": "Sustainable Architecture",
  "concepts": ["green building", "solar panels", "eco-friendly design"],
  "style": "photo",
  "max_images": 10
}

使用特定要求进行搜索

// 使用 search_images 工具
{
  "query": "mountain landscape sunrise",
  "aspect_ratio": "wide",
  "license_type": "commercial",
  "extension": "jpg",
  "size": "large",
  "page_size": 20
}

故障排除

常见问题

1. 速率限制错误：你达到了匿名 API 的限制。请等待一小时或实现认证。
2. 无搜索结果：请尝试使用更宽泛的搜索词或移除过滤器。
3. 连接错误：请检查你的互联网连接和防火墙设置。

调试模式

设置 DEBUG 环境变量：

DEBUG=mcp:* npx @mcp/openverse

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

贡献说明

欢迎贡献代码！请随时提交拉取请求。

开发指南

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

致谢

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