MCP Image Recognition Server

MCP图像识别服务器

一款 MCP 服务器，使用 Anthropic、OpenAI 和 Cloudflare Workers AI 视觉 API 提供图像识别功能。版本 1.2.1。

作者

该项目最初由@mario-andreschak创建。谢谢！
它目前由@zudsniper维护。

特征

• 使用 Anthropic Claude Vision、OpenAI GPT-4 Vision 或 Cloudflare Workers AI llava-1.5-7b-hf 进行图像描述
• 轻松与 Claude Desktop、Cursor 和其他 MCP 兼容客户端集成
• 支持 Docker 部署
• 支持 uvx 安装
• 支持多种图像格式（JPEG、PNG、GIF、WebP）
• 可配置的主要和后备提供商
• Base64 和基于文件的图像输入支持
• 使用 Tesseract OCR 进行可选文本提取

要求

• Python 3.8 或更高版本
• Tesseract OCR（可选）- 文本提取功能所需
  • Windows：从UB-Mannheim/tesseract下载并安装
  • Linux： sudo apt-get install tesseract-ocr
  • macOS： brew install tesseract

安装

选项 1：使用 uvx（推荐用于 Claude Desktop 和 Cursor）

1. 安装uv包管理器：

2. 使用 uvx 安装包：

3. 按照配置部分所述创建并配置环境文件

选项 2：使用 Docker

选项 3：从源头

1. 克隆存储库：

2. 创建并配置您的环境文件：

3. 构建项目：

一体化

Claude 桌面集成

1. 转到Claude >设置>开发人员>编辑配置> claude_desktop_config.json
2. 添加带有内联环境变量的配置：

光标集成

转到Cursor Settings > MCP并粘贴环境变量：

Docker 集成

选项 1：使用 DockerHub 镜像

将其添加到具有内联环境的 Claude Desktop 配置中：

对于 Cloudflare 配置：

用法

直接运行服务器

如果使用 pip/uvx 安装：

从源目录：

使用 Docker：

使用 MCP Inspector 以开发模式启动：

可用工具

1. describe_image
   • 目的：分析直接上传到聊天中的图像
   • 输入：Base64编码的图像数据
   • 输出：图像的详细描述
   • 最适合：直接上传到 Claude、Cursor 或其他聊天界面的图像
2. describe_image_from_file
   • 目的：处理来自文件系统的本地图像文件
   • 输入：图像文件的路径
   • 输出：图像的详细描述
   • 最适合：具有文件系统访问的本地开发
   • 注意：在 Docker 中运行时，需要卷映射（请参阅 Docker 文件访问部分）
3. describe_image_from_url
   • 目的：分析来自网页 URL 的图像，无需手动下载
   • 输入：可公开访问图像的 URL
   • 输出：图像的详细描述
   • 最适合：Web 图像、屏幕截图或任何具有公共 URL 的内容
   • 注意：使用类似浏览器的标头来避免速率限制

环境配置

• ANTHROPIC_API_KEY ：您的 Anthropic API 密钥。
• OPENAI_API_KEY ：您的 OpenAI API 密钥。
• CLOUDFLARE_API_KEY ：您的 Cloudflare API 密钥。
• CLOUDFLARE_ACCOUNT_ID ：您的 Cloudflare 帐户 ID。
• VISION_PROVIDER ：主要视觉提供商（ anthropic 、 openai或cloudflare ）。
• FALLBACK_PROVIDER ：可选的后备提供程序。
• LOG_LEVEL ：日志级别（DEBUG、INFO、WARNING、ERROR）。
• ENABLE_OCR ：启用 Tesseract OCR 文本提取（ true或false ）。
• TESSERACT_CMD ：Tesseract 可执行文件的可选自定义路径。
• OPENAI_MODEL ：OpenAI 模型（默认值： gpt-4o-mini ）。其他模型可以使用 OpenRouter 格式（例如anthropic/claude-3.5-sonnet:beta ）。
• OPENAI_BASE_URL ：OpenAI API 的可选自定义基本 URL。对于 OpenRouter，请设置为https://openrouter.ai/api/v1 。
• OPENAI_TIMEOUT ：OpenAI API 的可选自定义超时（以秒为单位）。
• CLOUDFLARE_MODEL ：Cloudflare Workers AI 模型（默认值： @cf/llava-hf/llava-1.5-7b-hf ）。
• CLOUDFLARE_MAX_TOKENS ：要生成的最大令牌数（默认值： 512 ）。
• CLOUDFLARE_TIMEOUT ：Cloudflare API 请求的超时时间（秒）（默认值： 60 ）。

使用 OpenRouter

OpenRouter 允许您使用 OpenAI API 格式访问各种模型。要使用 OpenRouter，请按照以下步骤操作：

1. 从 OpenRouter 获取 OpenAI API 密钥。
2. 将.env文件中的OPENAI_API_KEY设置为您的 OpenRouter API 密钥。
3. 将OPENAI_BASE_URL设置为https://openrouter.ai/api/v1 。
4. 使用 OpenRouter 格式将OPENAI_MODEL设置为所需模型（例如， anthropic/claude-3.5-sonnet:beta ）。
5. 将VISION_PROVIDER设置为openai 。

默认模型

• 人择： claude-3.5-sonnet-beta
• OpenAI： gpt-4o-mini
• Cloudflare Workers AI： @cf/llava-hf/llava-1.5-7b-hf
• OpenRouter：在OPENAI_MODEL中使用anthropic/claude-3.5-sonnet:beta格式。

发展

开发设置指南

设置开发环境

1. 克隆存储库：

2. 使用 uv 设置（推荐）：

使用 pip 的替代设置：

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e . # Or alternatively: pip install -r requirements.txt pip install -r requirements-dev.txt

3. 配置环境：

VS Code / DevContainer 开发

1. 使用远程容器扩展安装 VS Code
2. 在 VS Code 中打开项目文件夹
3. 出现提示时，单击“在容器中重新打开”
4. devcontainer 将构建并打开，并安装所有依赖项

使用 Claude Desktop 开发容器

1. 将环境文件传递给docker compose：

2. 将其添加到您的 Claude Desktop 配置中：

在本地测试您的更改

1. 以开发模式运行 MCP 服务器：

2. Inspector 提供了一个 Web 界面（通常位于http://localhost:3000 ），您可以在其中执行以下操作：
   • 向您的工具发送请求
   • 查看请求/响应日志
   • 调试实施过程中的问题
3. 测试特定工具：
   • 对于describe_image ：提供 base64 编码的图像
   • 对于describe_image_from_file ：提供本地图像文件的路径
   • 对于describe_image_from_url ：提供图像的 URL

与 Claude Desktop 集成进行测试

1. 临时修改您的 Claude Desktop 配置以使用您的开发版本：

2. 重新启动 Claude Desktop 以应用更改
3. 通过在对话中上传图片或提供图片 URL 进行测试

运行测试

运行所有测试：

运行特定的测试套件：

Docker 支持

构建 Docker 镜像：

运行容器：

Docker 文件访问限制

在 Docker 中运行 MCP 服务器时， describe_image_from_file工具只能访问容器内的文件。默认情况下，容器无法访问主机系统上的文件。要启用对本地文件的访问，必须在配置 MCP 服务器时明确映射目录。

重要提示：使用 Claude Desktop、Cursor 或其他需要上传图片到聊天的平台时，这些图片会存储在 Anthropic 的服务器上，MCP 服务器无法通过文件系统路径直接访问。在这种情况下，您应该：

1. 使用describe_image工具（适用于 base64 编码的图像）将图像直接上传到聊天室
2. 使用新的describe_image_from_url工具来处理在线托管的图像
3. 对于本地文件，确保目录正确映射到 Docker 容器

将本地目录映射到 Docker

要让 Docker 容器访问系统上的特定文件夹，请修改 MCP 服务器配置以包含卷映射：

例如，映射您的下载文件夹：

• Windows： -v "C:\\Users\\YourName\\Downloads:/app/images"
• macOS/Linux： -v "/Users/YourName/Downloads:/app/images"

然后使用容器路径访问文件： /app/images/your_image.jpg

执照

MIT 许可证 - 详情请参阅 LICENSE 文件。

使用 Cloudflare Workers AI

要使用 Cloudflare Workers AI 进行图像识别：

1. 登录Cloudflare 仪表板并选择您的帐户。
2. 转到AI >工人 AI 。
3. 选择使用 REST API并创建具有 Workers AI 权限的 API 令牌。
4. 在您的.env文件中设置以下内容：
   • CLOUDFLARE_API_KEY ：您的 Cloudflare API 令牌
   • CLOUDFLARE_ACCOUNT_ID ：您的 Cloudflare 帐户 ID
   • VISION_PROVIDER ：设置为cloudflare
   • CLOUDFLARE_MODEL ：可选，默认为@cf/llava-hf/llava-1.5-7b-hf

与人工智能助手一起使用

配置完成后，您的 AI 助手（例如 Claude）可以通过以下方式分析图像：

1. 直接在聊天中上传图片
2. 助手将自动使用 MCP 服务器分析图像
3. 助手将根据视觉 API 的输出详细描述图像

上传图片后的示例提示：

您还可以根据特定需求自定义提示：

或者

发布历史

• 1.2.1 (2025-03-28)：重新组织文档并改进 devcontainer 工作流程
• 1.2.0 (2025-03-28)：修复使用 httpx 和浏览器标头获取 URL 图像的问题，添加了 devcontainer 支持
• 1.1.0 （2025-03-28）：增强工具描述以便更好地选择，将 OpenAI SDK 更新至最新版本
• 1.0.1 (2025-03-28)：添加基于 URL 的图像识别、改进 Docker 文档并修复文件系统限制
• 1.0.0 (2025-03-28)：添加了 Cloudflare Workers AI 对 llava-1.5-7b-hf 模型的支持、Docker 支持和 uvx 兼容性
• 0.1.2 (2025-02-20)：改进了 OCR 错误处理并增加了 OCR 功能的全面测试覆盖率
• 0.1.1 (2025-02-19)：添加了 Tesseract OCR 支持，用于从图像中提取文本（可选功能）
• 0.1.0 （2025-02-19）：初始版本，支持 Anthropic 和 OpenAI 视觉

执照

MIT 许可证 - 详情请参阅 LICENSE 文件。

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

发布新版本

要发布新版本：

1. 更新pyproject.toml和setup.py中的版本
2. 将更改推送到release分支
3. GitHub Actions 将自动：
   • 运行测试
   • 构建并推送 Docker 镜像
   • 发布到 PyPI
   • 创建 GitHub 版本

CI/CD 所需的存储库机密：

• DOCKERHUB_USERNAME - Docker Hub 用户名
• DOCKERHUB_TOKEN - Docker Hub 访问令牌
• PYPI_API_TOKEN - PyPI API 令牌