MCP图片搜索服务器

Name: MCP图片搜索服务器
Author: yanjunz

作者：yanjunz13 星标更新：2025-05-08

安装使用来源：spider==github.com

项目介绍

MCP 图像搜索与图标生成服务

基于多个图像 API 的搜索服务和图标生成功能，特别设计用于与 Cursor MCP 服务集成。支持图像搜索、下载以及 AI 生成图标。

MCP 图像搜索工具示例

工作原理

此工具通过 MCP（模型控制协议）为 Cursor IDE 提供图像搜索和图标生成功能：

搜索图像连接到 Unsplash、Pexels 和 Pixabay 等图像来源，根据关键词搜索高质量图像
下载图像将搜索到的图像下载到指定位置，以便直接在项目中使用
生成图标根据文本描述生成自定义图标，以满足项目 UI 需求

系统工作流程

用户 (在Cursor中) → 向Claude/大模型提问 → 大模型调用MCP工具 → 工具处理请求 → 返回结果 → 大模型展示结果

例如，您可以在 Cursor 中向 Claude 提问：“帮我找到五张关于太空的照片”，Claude 将通过 MCP 工具搜索并显示这些照片，之后您可以进一步请求下载或生成特定图标。

功能

支持搜索多个图像来源（Unsplash、Pexels、Pixabay）
高质量图标生成（基于 Together AI）
简单易用的 API
完整的错误处理
自定义保存路径和文件名
调整图像大小

环境准备

1. Python 环境

Python 3.10+
下载地址：https://www.python.org/downloads/
推荐使用 pyenv 来管理 Python 版本：

# macOS 安装 pyenv
brew install pyenv

# 安装 Python
pyenv install 3.13.2
pyenv global 3.13.2

2. uv 包管理工具

uv 是一个快速的 Python 包管理工具，需要先安装：

# macOS 安装 uv
brew install uv

# 或者使用 pip 安装
pip install uv

3. 图像 API 密钥

Unsplash API 密钥

访问 Unsplash 开发者页面
注册/登录账户
创建一个新的应用
获取访问密钥

Pexels API 密钥

访问 Pexels API 页面
注册/登录账户
请求 API 密钥

Pixabay API 密钥

访问 Pixabay API 页面
注册/登录账户
获取 API 密钥

Together AI API 密钥

访问 Together AI API 密钥页面
注册/登录账户
创建一个新的 API 密钥

4. Cursor

下载并安装 Cursor IDE
确保 Cursor 正确配置了 Python 环境

安装与配置

克隆项目：

git clone https://github.com/yanjunz/mcp_search_images.git

安装依赖：

python3 -m pip install fastmcp requests

如果遇到证书问题，可以使用：

python3 -m pip install fastmcp requests --trusted-host pypi.org --trusted-host files.pythonhosted.org --upgrade --force-reinstall --no-cache-dir

配置 API 密钥：

从模板文件复制配置文件：

# 复制模板文件作为配置文件
cp config.json.template config.json

# 编辑配置文件，设置 API 密钥
nano config.json  # 或使用其他编辑器

在 config.json 中修改以下配置：

{
    "api": {
        "unsplash_access_key": "你的Unsplash访问密钥",
        "pexels_api_key": "你的Pexels API密钥",
        "pixabay_api_key": "你的Pixabay API密钥",
        "together_api_key": "你的Together API密钥",
        "timeout": 30,
        "max_retries": 3,
        "retry_delay": 5
    },
    // ...其他配置...
}

注意确保不要将包含 API 密钥的配置文件提交到版本控制系统。在项目 .gitignore 文件中配置忽略 config.json，但保留 config.json.template

运行服务

方法 1：直接使用 Python 运行

这是最简单的方法，直接使用 Python 运行服务：

python3.11 main.py

服务启动后，会显示以下信息：

启动图片搜索服务 - 端口: 5173
提供的工具: search_images, download_image, generate_icon
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:5173 (Press CTRL+C to quit)

方法 2：使用 fastmcp 命令运行

如果您已安装 fastmcp 包，也可以使用 fastmcp 命令来运行：

开发模式运行（带调试界面）：

fastmcp dev main.py

生产模式运行：

fastmcp run main.py

如果端口被占用，可以指定另一个端口：

PORT=5174 fastmcp dev main.py

方法 3：使用 uv 运行

如果您使用 uv 作为包管理工具：

uv run --with fastmcp fastmcp run main.py

或者在开发模式下：

uv run --with fastmcp fastmcp dev main.py

Cursor 和 MCP 的工作原理

为了更好地理解和解决连接问题，这里提供了 Cursor 如何与 MCP 服务交互的基本工作原理：

MCP 服务启动过程
- 当运行 python3.11 main.py 时，服务初始化并创建一个 SSE（服务器发送事件）应用程序
- 服务开始监听指定端口上的请求（默认 5173）
- 注册服务工具函数（search_images, download_image, generate_icon）
- 对于使用 ServerLink 方式连接的情况，服务需要在 /sse 路径上正确处理 SSE 请求
Cursor 连接过程
- 当在 Cursor 设置中添加 MCP 工具时，Cursor 尝试与提供的 URL 建立连接
- Cursor 发送初始化请求以检查服务是否正常响应
- 服务需要返回正确的 MCP 协议响应，包括可用工具列表
- 成功连接后，Cursor 将工具添加到可用工具列表中
诊断连接问题
- 检查服务是否正在运行：lsof -i :5173
- 检查网络连接：curl http://localhost:5173
- 检查服务是否正确实现了 MCP 协议：服务启动日志应显示注册的工具
- 检查防火墙和网络权限：本地服务有时可能会被防火墙阻止

完整的测试过程

# 1. 停止任何可能正在运行的服务
pkill -f "python.*main.py"

# 2. 启动服务（在前台运行以查看日志）
python3.11 main.py

# 3. 在新的终端窗口中，测试连接
curl http://localhost:5173

# 4. 测试 SSE 端点（用于 ServerLink 方式）
curl http://localhost:5173/sse

# 5. 在 Cursor 中添加 MCP 工具并测试

如果按照上述步骤连接仍然失败，您可能需要检查 Python 版本兼容性或确保依赖项正确安装。有时重新安装依赖项也可能有帮助：

python3.11 -m pip uninstall fastmcp mcp uvicorn starlette -y
python3.11 -m pip install fastmcp mcp uvicorn starlette

使用说明

在 Cursor IDE 中使用

确保服务正在运行

# 直接运行 Python 脚本
python3.11 main.py

服务启动后，会显示以下信息：

启动图片搜索服务 - 端口: 5173
提供的工具: search_images, download_image, generate_icon
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:5173 (Press CTRL+C to quit)

在 Cursor 中添加 MCP 服务：
- 打开 Cursor IDE
- 点击左下角的齿轮图标打开设置
- 选择“AI & Copilot”设置
- 在“MCP 工具”部分点击“添加 MCP 工具”
- 填写以下信息：
  - 名称：Image Search Service
  - 类型：SSE（服务器发送事件）
  - URL：http://localhost:5173
  - 点击“保存”
替代配置方法 某些版本的 Cursor 可能需要 ServerLink 配置：
- 名称：Image Search Service
- 类型：sse
- ServerLink：http://localhost:5173/sse
- 点击“保存”
注意如果出现“无法创建客户端”的错误，请检查以下几点：
1. 确认服务正在运行（通过 lsof -i :5173 检查端口是否被监听
2. 尝试在浏览器中访问 http://localhost:5173 测试连通性
3. 确保 URL 没有多余的斜杠或空格
4. 对于 ServerLink 方式，确保使用正确的端点路径 /sse
5. 重启服务后再尝试添加
6. 有时需要重启 Cursor IDE 以清除之前的连接缓存
开始使用 MCP 工具：
- 在 Cursor 中打开包含 Claude 或其他支持工具调用的大模型对话窗口
- 当服务运行时，大模型可以自动发现并使用该工具
- 如果大模型未能自动检测到工具，您可以提示它：“请使用图像搜索服务查找图像。”
在开发过程中随时使用：
- 在编写代码时，需要图标素材，可以直接向大模型描述需求
- 例如：“帮我在 Unsplash 上搜索 5 张关于‘人工智能’的图片。”
- 大模型将调用 MCP 工具搜索图像并显示结果
- 您可以进一步请求下载或生成自定义图标
查看图标保存位置：
- 默认情况下，图标保存在项目根目录下的 icons 文件夹中
- 您可以通过以下命令查看保存的图标：
```
ls -la icons
```

功能使用示例

搜索图像

您可以直接向大模型描述需求：

搜索关键词为"技术"的图片

或者更具体的描述：

请在 Unsplash 上搜索 5 张关于"人工智能"的图片

下载图像

当大模型显示搜索结果时，您可以请求下载特定图像：

下载第 2 张图片并保存为 tech-icon.png

或者指定保存路径：

将第 3 张图片下载到 /Users/username/Desktop/，文件名为 ai-image.jpg

生成图标

您可以提供详细的描述来生成符合要求的图标：

生成一个蓝色科技风格的图标，保存为 blue-tech.png

或者更详细的描述：

请创建一个扁平化设计的邮件图标，红色轮廓，白色背景，图标尺寸为 256x256，保存为 email-icon.png

实际对话示例

查看示例对话学习如何在实际使用中与 Claude/大模型互动以搜索和生成图标。

整合到项目工作流

在项目初期阶段批量生成图标：
- 在创建设计系统时，可以一次性生成多个相关图标
- 例如：“帮我生成一套应用图标，包括首页、设置、用户和消息通知。”
开发过程中按需搜索：
- 在编写代码时定位所需的图像资源
- 例如：“我正在开发一个天气应用，需要一些与天气相关的图标。”
项目完成阶段定制图标：
- 根据应用统一风格优化图标
- 例如：“生成一组与当前应用风格匹配的社交媒体分享图标”

最佳实践

使用明确关键词使用具体且明确的关键词以获得更准确的搜索结果
指定图像来源根据需求选择合适的图像来源（Unsplash 适合自然景观，Pixabay 适合商业图像等）
结构化命名保存使用结构化的命名保存图标，如 category-name-size.png
批量操作一次性请求多个相关图标而不是逐一请求
结合代码上下文在实际开发中提及代码上下文，使大模型更好地理解您的需求

故障排除

Cursor MCP 连接错误

如果您在 Cursor 中添加 MCP 服务时遇到“无法创建客户端”的错误，请尝试以下解决方案：

检查服务状态

# 检查服务是否正在运行
lsof -i :5173
# 如果没有输出，表示服务未运行，请启动服务
python3.11 main.py

测试连接

# 使用 curl 测试 API 连接
curl -v http://localhost:5173

修改连接设置
- 确保选择了正确的连接类型：SSE
- 尝试使用 IP 地址而不是 localhost：http://127.0.0.1:5173
- 确保 URL 不包含多余的斜杠：使用 http://localhost:5173 而不是 http://localhost:5173/
- 尝试使用 ServerLink 方式配置：
  - 类型：sse
  - ServerLink：http://localhost:5173/sse
- 某些版本的 Cursor 可能对 URL 格式有特定要求，两种方法都值得尝试
重启组件
- 停止并重新启动 MCP 服务
- 重启 Cursor IDE
- 如果您使用的是 macOS，请检查防火墙设置是否阻止了连接
检查日志
- 观察服务启动时的日志输出
- 尝试从 Cursor 连接时，检查服务器是否有新的日志输出
尝试其他端口
- 修改代码中的端口（例如，改为 5174）并重新启动服务：
```
uvicorn.run(sse_app, host="0.0.0.0", port=5174)
```

其他常见问题

如果您遇到任何问题，请检查：

服务是否正常运行
保存路径是否正确
目录权限是否正确
网络连接是否正常
API 密钥是否有效
Python 环境是否正确配置
uv 是否正确安装
依赖包是否完全安装

贡献

欢迎提交问题和拉取请求以改进项目。

许可证

MIT 许可证