# mcp图像搜索
## 基本信息
- Slug: `yanjunz-mcp_search_images`
- Source: modelscope
- Publisher: @yanjunz/mcp_search_images
- Categories: image-and-video-processing / search
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@yanjunz/mcp_search_images
## 简介
一种基于多个图像API和图标生成能力的搜索服务，专为与Cursor MCP服务集成而设计。支持图像搜索、下载和AI生成的图标。
## 安装提示

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

## MCP Server 详情

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

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

![MCP图像搜索工具示例](examples/mcp_search_example.png)

## 工作原理

本工具通过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 版本：

```bash
# macOS 安装 pyenv
brew install pyenv

# 安装 Python
pyenv install 3.13.2
pyenv global 3.13.2
```


### 2. uv 包管理工具

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

```bash
# macOS 安装 uv
brew install uv

# 或者使用 pip 安装
pip install uv
```


### 3. 图片API密钥

#### Unsplash API 密钥
1. 访问 [Unsplash Developers](https://unsplash.com/developers)
2. 注册/登录账号
3. 创建新的应用程序
4. 获取 Access Key

#### Pexels API 密钥
1. 访问 [Pexels API](https://www.pexels.com/api/)
2. 注册/登录账号
3. 请求API密钥

#### Pixabay API 密钥
1. 访问 [Pixabay API](https://pixabay.com/api/docs/)
2. 注册/登录账号
3. 获取API密钥

#### Together AI API 密钥
1. 访问 [Together AI API Keys](https://api.together.xyz/keys)
2. 注册/登录账号
3. 创建新的 API 密钥

### 4. Cursor

* 下载并安装 [Cursor IDE](https://cursor.sh/)
* 确保 Cursor 已正确配置 Python 环境

## 安装配置

1. 克隆项目：

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


2. 安装依赖：

```bash
python3 -m pip install fastmcp requests
```


出现证书问题可以使用：

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


3. 配置 API 密钥：

从模板创建配置文件：

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

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


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

```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运行服务：

```bash
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. 开发模式运行（带调试界面）：

```bash
fastmcp dev mcp_search_images.py
```


2. 生产模式运行：

```bash
fastmcp run mcp_search_images.py
```


3. 如果端口被占用，可以指定其他端口：

```bash
PORT=5174 fastmcp dev mcp_search_images.py
```


### 方法三：使用uv运行

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

```bash
uv run --with fastmcp fastmcp run mcp_search_images.py
```


或者在开发模式下：

```bash
uv run --with fastmcp fastmcp dev mcp_search_images.py
```


### Cursor与MCP的工作原理

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

1. **MCP服务启动流程**：
   * 当运行`python3.11 mcp_search_images.py`时，服务初始化并创建SSE（Server-Sent Events）应用
   * 服务在指定端口（默认5173）开始监听请求
   * 服务注册工具函数（search_images, download_image, generate_icon）
   * 对于使用ServerLink方式的连接，服务需要在`/sse`路径上正确处理SSE请求

2. **Cursor连接流程**：
   * 当在Cursor设置中添加MCP工具时，Cursor尝试与提供的URL建立连接
   * Cursor发送初始化请求，检查服务是否正常响应
   * 服务需要返回正确的MCP协议响应，包括可用工具列表
   * 连接成功后，Cursor会将该工具添加到可用工具列表
   
3. **诊断连接问题**：
   * 检查服务是否在运行：`lsof -i :5173`
   * 检查网络连接：`curl http://localhost:5173`
   * 检查服务是否正确实现MCP协议：服务启动日志应显示注册的工具
   * 检查防火墙和网络权限：本地服务有时可能被防火墙阻止
   
4. **完整的测试流程**：
   ```bash
   # 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版本兼容性或依赖包是否正确安装。有时重新安装依赖包也有帮助：

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


## 使用说明

### 在 Cursor IDE 中使用

1. 确保服务正在运行
   ```bash
   # 直接运行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服务:
   * 打开Cursor IDE
   * 点击左下角的齿轮图标，打开设置
   * 选择"AI & Copilot"设置
   * 在"MCP工具"部分点击"添加MCP工具"
   * 填写以下信息:
     - 名称: 图片搜索服务
     - 类型: 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以清除之前的连接缓存

3. 开始使用MCP工具:
   * 在Cursor中打开包含Claude或其他支持工具调用的大模型对话窗口
   * 当服务正在运行时，大模型可以自动发现并使用该工具
   * 如果大模型未自动发现工具，可以提示它:"请使用图片搜索服务来查找图片"

4. 在开发过程中随时使用:
   * 编写代码时需要图标素材，可以直接向大模型描述需求
   * 例如:"帮我找一些适合作为登录按钮的图标"
   * 大模型会调用MCP工具搜索图片并展示结果
   * 你可以进一步要求下载或生成自定义图标

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

### 功能使用示例

#### 搜索图片

可以直接向大模型描述需求:
```
搜索关键词为"technology"的图片
```
或更具体的描述:
```
请在Unsplash上搜索5张关于"artificial intelligence"的图片
```


#### 下载图片

当大模型显示搜索结果后，你可以要求下载特定图片:
```
下载第2张图片并保存为tech-icon.…