AI导哈

图像处理服务器

ImageOps MCP Server 是一个基于FastMCP的Python服务器，提供高级图像处理功能，包括图像获取、格式转换、对象检测与分割、边缘检测等，适用于AI驱动的工作流集成。

  • by sahiltarlana
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 sahiltarlana/image_mcp_server

使用说明

ImageOps MCP服务器

imageops-mcp-server 是一个基于FastMCP的Python服务器，专为高级图像处理任务而设计。它提供了一套工具，用于从URL或本地文件路径获取、操作和分析图像。该服务器利用YOLOv8和YOLOv11模型进行对象检测和分割，利用OpenCV进行边缘检测，利用PIL进行图像格式转换和裁剪。该项目具有可扩展性、高效性，并与现代人工智能驱动的工作流程兼容，使其适合与Claude Desktop和Cursor等工具集成。

特性

  • 图像获取：从URL或本地文件检索图像，对大图像（<1MB）进行自动压缩。
  • 格式转换：将图像转换为JPEG、PNG或GIF格式，并可选择保存到输出目录。
  • 目标检测：使用YOLOv8执行对象检测，返回标签、置信度得分和边界框坐标。
  • 对象分割：应用YOLOv11分割，以可定制的透明度在检测到的对象上叠加彩色蒙版。
  • 图像剪裁：使用边界框坐标裁剪图像的特定区域，与YOLO检测结果兼容。
  • Canny边缘提取：使用具有可调阈值的OpenCV Canny算法检测图像中的边缘。
  • 日志记录：控制台和文件的全面日志记录，带有时间戳的日志用于调试和监控。
  • 目录管理：自动创建必要的目录(data, Temp, output)用于日志和处理后的图像。
  • 集成就绪：专为与Claude Desktop和Cursor等AI工具配合使用而设计，可实现无缝的工作流集成。
  • 缩略图创建：生成具有指定大小的方形缩略图，保持纵横比。
  • 图像过滤器：应用模糊、锐化、增强或复古效果，强度可调。
  • 3D点云生成：使用深度Anything-V2-Small-hf从2D图像创建3D点云进行深度估计。

先决条件

要设置和运行 imageops-mcp-server，确保已安装以下内容：

  • python：3.13或更高版本
  • 紫外线：现代Python包和项目管理器（推荐用于依赖关系管理）
  • Git：用于克隆存储库
  • 克劳德桌面 （可选）：用于在AI驱动的工作流中与服务器交互
  • 光标 （可选）：用于代码编辑和与AI助手的集成
  • 操作系统：与Windows、macOS或Linux兼容

安装说明

按照以下步骤使用设置项目 uv:

  1. 克隆存储库:

    git clone https://github.com/your-username/imageops-mcp-server.git
cd imageops-mcp-server

  2. 安装uv: 如果你没有 uv 已安装，请按照官方安装说明进行操作：

    # On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows (PowerShell)
iwr -useb https://astral.sh/uv/install.ps1 | iex

  3. 创建虚拟环境并安装依赖项: 使用 uv 设置项目环境并安装中指定的依赖项 project.toml:

    uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install .

    此命令读取 project.toml 文件和安装依赖项，如 fastmcp, httpx, ultralytics, opencv-contrib-python, pillow以及其他。

  4. 验证目录结构: 如果以下目录不存在，服务器会自动创建它们：

    • ./data：存储日志文件（例如。， DD-MM-YY.log).
    • ./Temp：中间文件的临时存储。
    • ./output：存储处理后的图像（例如，转换、裁剪、分割或边缘检测图像）。

    确保您在项目目录中具有写入权限。

运行服务器

要启动FastMCP服务器，请运行主脚本：

uv run image_loader.py

服务器使用 stdio 传输，允许它处理来自兼容客户端的请求，如Claude Desktop或自定义脚本。

测试与 mcp dev

这 mcp dev 命令（部分 mcp CLI）允许您以交互方式测试服务器的工具。请按照以下步骤操作：

  1. 确保依赖关系: 确认 mcp[cli] 已安装（包含在 project.toml).

  2. 跑 mcp dev: 在项目目录中，激活虚拟环境并启动开发工具：

    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
mcp dev image_loader.py

  3. 测试工具: 这 mcp dev 界面允许您直接调用服务器的工具。例如：

    • 获取图像:
      fetch_image "https://ultralytics.com/images/bus.jpg"
      返回一个 Image 如果获取失败，则显示对象或错误消息。
    • 获取图像尺寸并保存:
      get_image_dimensions_and_save "https://ultralytics.com/images/bus.jpg"
      返回一个包含维度和保存路径的字典。
    • 转换图像格式:
      convert_image_format "https://ultralytics.com/images/bus.jpg" "png" true
      将图像转换为PNG并保存。
    • 检测物体:
      detect_objects_yolo "https://ultralytics.com/images/bus.jpg" true
      执行YOLOv8对象检测并保存带注释的图像。
    • 裁剪对象:
      crop_the_object "https://ultralytics.com/images/bus.jpg" 100 150 200 300 true
      裁剪指定区域并保存。
    • 分段对象:
      segment_objects_yolo "https://ultralytics.com/images/bus.jpg" 0.5 true
      以0.5的透明度执行YOLOv11分割。
    • Canny边缘提取:
      canny_edge_detection "https://ultralytics.com/images/bus.jpg" 100 200 true
      应用具有指定阈值的Canny边缘检测。
    • 缩略图创建:
      create_thumbnail "https://ultralytics.com/images/bus.jpg" 128 true
      为图像创建缩略图。
    • 图像过滤器:
      apply_image_filters "https://ultralytics.com/images/bus.jpg" blur 1 true
      对图像应用图像过滤器。
    • 3D点云生成:
      generate_3d_point_cloud "https://ultralytics.com/images/bus.jpg" true false
      生成图像的3D.pyl文件。

  4. 检查输出:

    • 日志保存在 ./data 目录（例如。， 09-07-25.log).
    • 处理后的图像保存在 ./output 带有时间戳文件名的目录（例如。， image_2025-07-09_171823.jpg).

连接到克劳德桌面

要连接 imageops-mcp-server 访问Claude Desktop并使用其工具：

  1. 启动服务器: 确保服务器正在您的项目目录中运行：

    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv run python image_mcp_server.py

  2. 配置Claude桌面:

    • 打开克劳德桌面并导航到 设置 （通常位于顶部导航栏或菜单中）。
    • 首选 特性 > MCP服务器.
    • 点击 +添加新的MCP服务器 添加新的服务器配置。
    • 输入以下配置，替换 /path/to/imageops-mcp-server 使用项目目录的绝对路径：
      {
  "mcpServers": {
    "imageops": {
      "command": "uv",
      "args": ["--directory", "/path/to/imageops-mcp-server", "run", "python", "image_mcp_server.py"]
    }
  }
}
    • 保存配置。Claude Desktop将使用 uv 使用以下命令在指定目录中运行服务器 stdio 运输。

  3. 与服务器交互:

    • 在Claude Desktop的聊天界面中，您可以通过使用自然语言提示或结构化JSON调用其工具向服务器发送请求。
    • Claude Desktop将与服务器通信并显示结果，例如JSON响应或对已保存图像的引用 ./output 目录。

  4. 示例提示:

    • 获取图像:

      Fetch the image from https://ultralytics.com/images/bus.jpg and process it.

      预期响应：返回一个 Image 对象或处理确认，图像保存在 ./output.

    • 检测物体:

      Perform object detection on https://ultralytics.com/images/bus.jpg using YOLOv8 and save the result.

      预期响应：返回一个JSON字典，其中包含检测到的对象、边界框、置信度得分和带注释图像的保存路径。

    • 转换图像格式:

      Convert https://ultralytics.com/images/bus.jpg to PNG format and save it.

      预期响应：返回一个 Image PNG格式的对象，并确认保存的路径。

    • 分段对象:

      Segment objects in https://ultralytics.com/images/bus.jpg with 0.5 transparency and save the output.

      预期响应：返回一个JSON字典，其中包含分割图像、检测细节和保存的路径。

    • 裁剪对象:

      Crop the region (100, 150, 200, 300) from https://ultralytics.com/images/bus.jpg and save it.

      预期响应：返回一个包含裁剪图像和保存路径的JSON字典。

    • Canny边缘提取:

      Apply Canny edge detection to https://ultralytics.com/images/bus.jpg with thresholds 100 and 200, and save the result.

      预期响应：返回一个JSON字典，其中包含边缘检测图像和保存的路径。

    • 创建缩略图:

      Create a 128x128 thumbnail from https://ultralytics.com/images/bus.jpg and save it.

      预期响应：返回一个包含缩略图、尺寸和保存路径的JSON字典。

    • 应用图像过滤器:

      Apply a blur filter with intensity 1.0 to https://ultralytics.com/images/bus.jpg and save the result.

      预期响应：返回一个JSON字典，其中包含过滤后的图像和保存的路径。

    • 生成三维点云:

      Generate a 3D point cloud from https://ultralytics.com/images/bus.jpg and save it as a .ply file.

      预期响应：返回一个包含点云数据和保存的.play文件路径的JSON字典。

  5. 查看结果:

    • Claude Desktop将显示JSON响应，包括检测细节、图像数据或文件路径。
    • 检查 ./output 保存图像的目录（例如。， image_2025-07-09_174523.jpg).

连接到游标

要连接 imageops-mcp-server 使用光标并使用其工具：

  1. 在游标中打开项目:

    • 启动Cursor并打开 imageops-mcp-server 项目目录。
    • 光标将检测 project.toml 文件并提示您使用以下命令设置环境 uv。按照提示或手动运行：
      uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install .

  2. 配置光标:

    • 打开光标并转到 设置 （导航栏> 光标设置).
    • 引导到 特性 >.mob
    • 点击 +添加新的MCP服务器.
    • 添加以下配置，替换 /path/to/imageops-mcp-server 使用项目目录的绝对路径：
      {
  "mcpServers": {
    "imageops": {
      "command": "uv",
      "args": ["--directory", "/path/to/imageops-mcp-server", "run", "python", "image_mcp_server.py"]
    }
  }
}
    • 保存配置。这允许Cursor通过以下方式与服务器通信 stdio.

  3. 与服务器交互:

    • 使用Cursor的聊天界面或测试脚本向服务器发送请求。
    • 或者，在Cursor中创建一个Python脚本，以编程方式调用工具：
      from mcp.client import AsyncClient
import asyncio

async def test_tools():
    async with AsyncClient(transport='stdio') as client:
        result = await client.call_tool('detect_objects_yolo', {
            'image_source': 'https://ultralytics.com/images/bus.jpg',
            'save': True
        })
        client.write(result)

asyncio.run(test_tools())
    • 在Cursor的终端中运行脚本以测试服务器功能。

  4. 示例提示:

    • 获取图像:

      Please fetch and process the image from https://ultralytics.com/images/bus.jpg.

      预期响应：Cursor的AI将触发 fetch_image 工具并返回处理后的图像数据或确认。

    • 目标检测:

      Detect objects in https://ultralytics.com/images/bus.jpg using YOLOv8 and save the annotated image.

      预期响应：返回一个JSON响应，其中包含检测详细信息和保存的带注释图像的路径。

    • 图像转换:

      Convert https://ultralytics.com/images/bus.jpg to GIF format and save it.

      预期响应：确认转换为GIF并提供保存的路径。

    • 对象分割:

      Segment objects in https://ultralytics.com/images/bus.jpg with 0.7 transparency and save the result.

      预期响应：返回一个包含分割图像、检测结果和保存路径的JSON字典。

    • 裁剪对象:

      Crop the region (x_min: 100, y_min: 150, x_max: 200, y_max: 300) from https://ultralytics.com/images/bus.jpg and save it.

      预期响应：返回一个包含裁剪图像和保存路径的JSON字典。

    • Canny边缘提取:

      Perform Canny edge detection on https://ultralytics.com/images/bus.jpg with thresholds 50 and 150, and save the output.

      预期响应：返回一个JSON字典，其中包含边缘检测图像和保存的路径。

    • 创建缩略图:

      Create a 128x128 thumbnail from https://ultralytics.com/images/bus.jpg and save it.

      预期响应：Cursor的AI触发 create_thumbnail 工具，返回缩略图数据和保存的路径。

    • 应用图像过滤器:

      Apply a vintage filter with intensity 1.0 to https://ultralytics.com/images/bus.jpg and save it.

      预期响应：返回一个JSON响应，其中包含过滤后的图像和保存的路径。

    • 生成三维点云:

      Generate a 3D point cloud from https://ultralytics.com/images/bus.jpg and save it as a .ply file.

      预期响应：返回包含点云数据和保存的.play文件路径的JSON响应。

  5. AI协助:

    • 使用Cursor的AI聊天来生成新工具或优化现有代码。例如，提示：
      Add a new MCP tool to rotate images by a specified angle.
      Cursor的AI可以生成代码，您可以将其添加到 image_mcp_server.py.

  6. 查看结果:

    • 游标将在终端或聊天界面中显示JSON响应或脚本输出。
    • 检查 ./output 保存图像的目录。

项目结构

imageops-mcp-server/
├── data/                    # Directory for log files
├── Temp/                    # Directory for temporary files
├── output/                  # Directory for processed images
├── image_mcp_server.py      # Main server script
├── project.toml             # Project configuration and dependencies
└── README.md                # Project documentation

依赖项

该项目依赖于以下Python包（在 project.toml):

  • asyncio>=3.4.3：用于异步编程。
  • fastmcp>=2.9.0：用于FastMCP服务器框架。
  • httpx>=0.28.1：用于获取图像的HTTP请求。
  • opencv-contrib-python>=4.11.0.86：用于Canny边缘检测和图像处理。
  • pillow>=11.2.1：用于图像处理（裁剪、格式转换）。
  • ultralytics>=8.3.162：适用于YOLOv8和YOLOv11型号。
  • mcp[cli]==1.9.4：用于MCP CLI和开发工具。
  • transformers>=4.47.0：用于3D点云生成中的深度估计。
  • open3d>=0.18.0：用于点云创建和可视化。
  • tenacity>=9.0.0：用于URL获取中的重试逻辑。
  • 其他： ipykernel, logging, matplotlib, nest-asyncio, mcp-use.

故障排除

  • 依赖性问题：确保 uv 已正确安装所有依赖项。跑 uv pip list 以验证。
  • YOLO模型错误：如果YOLO模型无法加载，请确保 ultralytics 已安装模型文件(yolov8n.pt, yolo11n-seg.pt)可访问。
  • 找不到文件：验证图像源路径或URL是否正确且可访问。
  • 权限错误：确保对的写入权限 data, Temp，以及 output 目录。
  • 超时错误：对于基于URL的图像，请检查网络连接或增加 httpx 代码超时。 颜色问题：修复了RGB/BGR转换 apply_image_filters 以防止颜色交换（例如红色显示为蓝色）。
  • PIL错误：更正了中的无效模式参数 apply_image_filters 为了 PILImage.fromarray，解析“参数1必须是str，而不是int”错误。
  • 深度模型误差：确保 transformers 和 open3d 安装用于 generate_3d_point_cloud。如果Depth Anything模型无法加载，请检查网络连接或重新安装 transformers.

贡献

欢迎投稿！贡献：

  1. 分叉存储库。
  2. 创建新分支(git checkout -b feature/your-feature).
  3. 进行更改并提交(git commit -m "Add your feature").
  4. 推到分支(git push origin feature/your-feature).
  5. 打开一个pull请求。

请确保代码符合PEP 8标准，并包括适当的测试。

许可证

该项目根据MIT许可证获得许可。请参阅 LICENSE 文件以获取详细信息。

相关 MCP