🚀 @mcp/openverse
@mcp/openverse 是一个 MCP（模型上下文协议）服务器，它提供了从 Openverse 搜索和获取开放许可图像的工具。借助该服务器，用户能够轻松地找到符合各种需求的开放许可图像。
🚀 快速开始
你可以通过以下步骤快速使用 @mcp/openverse 服务器：
- 安装服务器（具体安装方式见“📦 安装指南”）。
- 配置 Claude Desktop（具体配置方式见“💻 使用示例”）。
- 开始使用服务器提供的工具进行图像搜索和获取。
✨ 主要特性
- 🔍 搜索知识共享许可（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
}
故障排除
常见问题
- 速率限制错误：你达到了匿名 API 的限制。请等待一小时或实现认证。
- 无搜索结果：请尝试使用更宽泛的搜索词或移除过滤器。
- 连接错误：请检查你的互联网连接和防火墙设置。
调试模式
设置 DEBUG 环境变量：
DEBUG=mcp:* npx @mcp/openverse
📄 许可证
本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。
贡献说明
欢迎贡献代码！请随时提交拉取请求。
开发指南
- 遵循 TypeScript 最佳实践。
- 为新功能添加测试。
- 更新文档。
- 确保所有工具都有适当的错误处理。