mcp search images

Local 2025-09-01 00:40:08 0
search @yanjunz/mcp_search_images

A search service based on multiple image APIs and icon generation capabilities, specifically designed for integration with Cursor MCP service. Supports image search, download, and AI-generated icons.

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

MCP图像搜索工具示例

工作原理

本工具通过MCP (Model Control Protocol) 为Cursor IDE提供图像搜索和图标生成功能：

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

系统工作流程

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

比如，你可以在Cursor中向Claude询问"帮我找5张关于太空的图片"，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 密钥

  1. 访问 Unsplash Developers
  2. 注册/登录账号
  3. 创建新的应用程序
  4. 获取 Access Key

Pexels API 密钥

  1. 访问 Pexels API
  2. 注册/登录账号
  3. 请求API密钥

Pixabay API 密钥

  1. 访问 Pixabay API
  2. 注册/登录账号
  3. 获取API密钥

Together AI API 密钥

  1. 访问 Together AI API Keys
  2. 注册/登录账号
  3. 创建新的 API 密钥

4. Cursor

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

安装配置

  1. 克隆项目：
git clone https://github.com/yanjunz/mcp_search_images.git
  1. 安装依赖：
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
  1. 配置 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。

运行服务

方法一：直接使用Python运行

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

python3.11 mcp_search_images.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)

方法二：使用fastmcp命令运行

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

  1. 开发模式运行（带调试界面）：
fastmcp dev mcp_search_images.py
  1. 生产模式运行：
fastmcp run mcp_search_images.py
  1. 如果端口被占用，可以指定其他端口：
PORT=5174 fastmcp dev mcp_search_images.py

方法三：使用uv运行

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

uv run --with fastmcp fastmcp run mcp_search_images.py

或者在开发模式下：

uv run --with fastmcp fastmcp dev mcp_search_images.py

Cursor与MCP的工作原理

为了更好地理解和解决连接问题，以下是Cursor与MCP服务交互的基本工作原理：

  1. MCP服务启动流程：
  2. 当运行python3.11 mcp_search_images.py时，服务初始化并创建SSE（Server-Sent Events）应用
  3. 服务在指定端口（默认5173）开始监听请求
  4. 服务注册工具函数（search_images, download_image, generate_icon）

  5. 对于使用ServerLink方式的连接，服务需要在/sse路径上正确处理SSE请求

  6. Cursor连接流程：

  7. 当在Cursor设置中添加MCP工具时，Cursor尝试与提供的URL建立连接
  8. Cursor发送初始化请求，检查服务是否正常响应
  9. 服务需要返回正确的MCP协议响应，包括可用工具列表

  10. 连接成功后，Cursor会将该工具添加到可用工具列表

  11. 诊断连接问题：

  12. 检查服务是否在运行：lsof -i :5173
  13. 检查网络连接：curl http://localhost:5173
  14. 检查服务是否正确实现MCP协议：服务启动日志应显示注册的工具

  15. 检查防火墙和网络权限：本地服务有时可能被防火墙阻止

  16. 完整的测试流程： 

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

# 2. 启动服务（在前台运行以查看日志）
python3.11 mcp_search_images.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 中使用

  1. 确保服务正在运行 

    # 直接运行Python脚本
python3.11 mcp_search_images.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. 在Cursor中添加MCP服务:

  3. 打开Cursor IDE
  4. 点击左下角的齿轮图标，打开设置
  5. 选择"AI & Copilot"设置
  6. 在"MCP工具"部分点击"添加MCP工具"
  7. 填写以下信息:
    • 名称: 图片搜索服务
    • 类型: SSE (Server-Sent Events)
    • URL: http://localhost:5173
    • 点击"保存"

备选配置方法: * 某些版本的Cursor可能需要使用ServerLink配置: - 名称: 图片搜索服务 - 类型: sse - ServerLink: http://localhost:5173/sse - 点击"保存"

注意: 如果出现"Fail to create client"错误，请检查以下几点: 1. 确认服务正在运行 (通过lsof -i :5173检查端口是否被监听) 2. 尝试在浏览器中访问http://localhost:5173测试连接性 3. 确保URL没有多余的斜杠或空格 4. 对于ServerLink方式，确保使用正确的端点路径/sse 5. 重启服务后再次尝试添加 6. 有时需要重启Cursor IDE以清除之前的连接缓存

  1. 开始使用MCP工具:
  2. 在Cursor中打开包含Claude或其他支持工具调用的大模型对话窗口
  3. 当服务正在运行时，大模型可以自动发现并使用该工具

  4. 如果大模型未自动发现工具，可以提示它:"请使用图片搜索服务来查找图片"

  5. 在开发过程中随时使用:

  6. 编写代码时需要图标素材，可以直接向大模型描述需求
  7. 例如:"帮我找一些适合作为登录按钮的图标"
  8. 大模型会调用MCP工具搜索图片并展示结果

  9. 你可以进一步要求下载或生成自定义图标

  10. 查看图标保存位置:

  11. 默认情况下，图标会保存在项目根目录下的icons文件夹中
  12. 可以通过以下命令查看已保存的图标: 
    ls -la icons

功能使用示例

搜索图片

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

搜索关键词为"technology"的图片
或更具体的描述: 
请在Unsplash上搜索5张关于"artificial intelligence"的图片

下载图片

当大模型显示搜索结果后，你可以要求下载特定图片: 

下载第2张图片并保存为tech-icon.png
或者指定保存路径: 
将第3张图片下载到/Users/username/Desktop/，文件名为ai-image.jpg

生成图标

可以提供详细的描述来生成符合需求的图标: 

生成一个蓝色科技风格的图标，保存为blue-tech.png
或者更详细的描述: 
请创建一个扁平化设计的邮件图标，红色轮廓，白色背景，图标尺寸为256x256，保存为email-icon.png

实际对话示例

查看示例对话了解如何在实际使用中与Claude/大模型交互来搜索和生成图标。

集成到项目工作流

  1. 在项目初始阶段批量生成图标:
  2. 创建设计系统时，可以一次性生成多个相关图标

  3. 例如:"帮我生成一套包含主页、设置、用户、消息通知的应用图标"

  4. 开发过程中按需搜索:

  5. 在编写代码时随时查找所需图片资源

  6. 例如:"我正在开发一个天气应用，需要几个天气相关的图标"

  7. 项目完善阶段定制图标:

  8. 根据应用风格统一优化图标
  9. 例如:"生成一组与我当前应用风格一致的社交媒体分享图标"

最佳实践

  1. 使用明确的关键词: 搜索时使用具体、明确的关键词获得更精确的结果
  2. 指定图片源: 根据需求选择合适的图片源（Unsplash适合自然风光，Pixabay适合商业图片等）
  3. 保存结构化命名: 为图标使用结构化命名，如category-name-size.png
  4. 批量操作: 一次性请求多个相关图标而不是逐个请求
  5. 与代码结合: 在实际开发中提及代码上下文，大模型可以更准确地理解你的需求

错误排查

Cursor MCP连接错误

如果在Cursor中添加MCP服务时遇到"Fail to create client"错误，请尝试以下解决方法：

  1. 检查服务状态： 

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

  2. 测试连接： 

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

  3. 修改连接设置：

  4. 确保选择了正确的连接类型：SSE
  5. 尝试使用IP地址代替localhost：http://127.0.0.1:5173
  6. 确保URL不含额外斜杠：使用http://localhost:5173而非http://localhost:5173/
  7. 尝试使用ServerLink方式配置：
    • 类型: sse
    • ServerLink: http://localhost:5173/sse

  8. 有些版本的Cursor可能对URL格式有特定要求，两种方式都值得尝试

  9. 重启组件：

  10. 停止并重启MCP服务
  11. 重启Cursor IDE

  12. 如果使用macOS，检查防火墙设置是否阻止了连接

  13. 检查日志：

  14. 观察服务启动时的日志输出

  15. 当尝试从Cursor连接时，查看服务端有无新的日志输出

  16. 尝试其他端口：

  17. 修改代码中的端口（如改为5174）并重启服务： 
    uvicorn.run(sse_app, host="0.0.0.0", port=5174)

其他常见问题

如果遇到问题，请检查：

  1. 服务是否正常运行
  2. 保存路径是否正确
  3. 目录权限是否正确
  4. 网络连接是否正常
  5. API 密钥是否有效
  6. Python 环境是否正确配置
  7. uv 是否正确安装
  8. 依赖包是否完整安装

贡献

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

许可

MIT License