Claude Vision & GPT-4 Vision图像识别工具

使用Anthropic Claude Vision和OpenAI GPT-4 Vision API提供图像识别功能，支持多种图像格式，并通过Tesseract OCR提供可选的文本提取。

image-and-video-processing

621 查看 · 2026-07-07 更新

简介

使用Anthropic Claude Vision和OpenAI GPT-4 Vision API提供图像识别功能，支持多种图像格式，并通过Tesseract OCR提供可选的文本提取。

简介

使用Anthropic Claude Vision和OpenAI GPT-4 Vision API提供图像识别功能，支持多种图像格式，并通过Tesseract OCR提供可选的文本提取。

MCP 图像识别服务器

一个使用 Anthropic、OpenAI 和 Cloudflare Workers AI 视觉 API 提供图像识别功能的 MCP 服务器。版本 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）

安装 uv 包管理器：

pip install uv

使用 uvx 安装包：

uvx install mcp-image-recognition

按照配置部分描述创建并配置您的环境文件

选项 2：使用 Docker

docker pull zudsniper/mcp-image-recognition:latest

# Create a .env file first, then run:
docker run -it --env-file .env zudsniper/mcp-image-recognition

选项 3：从源代码安装

克隆仓库：

git clone https://github.com/zudsniper/mcp-image-recognition.git
cd mcp-image-recognition

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

cp .env.example .env
# Edit .env with your API keys and preferences

构建项目：

pip install -e .

集成

Claude Desktop 集成

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

{
    "mcpServers": {
        "image-recognition": {
            "command": "uvx",
            "args": [
                "mcp-image-recognition"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

Cursor 集成

转到 Cursor 设置 > MCP 并粘贴带有环境变量的内容：

VISION_PROVIDER=openai OPENAI_API_KEY=your-api-key OPENAI_MODEL=gpt-4o uvx mcp-image-recognition

Docker 集成

选项 1：使用 DockerHub 镜像

将此添加到您的 Claude Desktop 配置中，带内联环境变量：

{
    "mcpServers": {
        "image-recognition": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "zudsniper/mcp-image-recognition:latest"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key", 
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

对于 Cloudflare 配置：

"env": {
    "VISION_PROVIDER": "cloudflare",
    "CLOUDFLARE_API_KEY": "your-api-key",
    "CLOUDFLARE_ACCOUNT_ID": "your-account-id"
}

使用

直接运行服务器

如果通过 pip/uvx 安装：

mcp-image-recognition

从源目录运行：

python -m image_recognition_server.server

使用 Docker 运行：

docker run -it --env-file .env zudsniper/mcp-image-recognition

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

npx @modelcontextprotocol/inspector mcp-image-recognition

可用工具

describe_image
- 用途: 分析直接上传到聊天中的图片
- 输入: Base64 编码的图片数据
- 输出: 图片的详细描述
- 最适合: 直接上传到 Claude、Cursor 或其他聊天界面的图片
describe_image_from_file
- 用途: 处理文件系统中的本地图片文件
- 输入: 图片文件的路径
- 输出: 图片的详细描述
- 最适合: 有文件系统访问权限的本地开发
- 注意: 在 Docker 中运行时，需要进行卷映射（请参阅 Docker 文件访问部分）
describe_image_from_url
- 用途: 无需手动下载即可分析来自网络 URL 的图片
- 输入: 公开可访问的图片 URL
- 输出: 图片的详细描述
- 最适合: 网页图片、截图或任何具有公共 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，请按照以下步骤操作：

从 OpenRouter 获取一个 OpenAI API 密钥。
在您的 .env 文件中将 OPENAI_API_KEY 设置为您的 OpenRouter API 密钥。
将 OPENAI_BASE_URL 设置为 https://openrouter.ai/api/v1。
将 OPENAI_MODEL 设置为您想要使用的模型，并使用 OpenRouter 格式 (例如, anthropic/claude-3.5-sonnet:beta)。
将 VISION_PROVIDER 设置为 openai。

默认模型

Anthropic: 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 格式。

开发

开发环境设置指南

设置开发环境

克隆仓库:

git clone https://github.com/zudsniper/mcp-image-recognition.git
cd mcp-image-recognition

使用 uv 进行设置（推荐）:

# Install uv if not installed
pip install uv

# Create virtual environment and install deps
uv venv
uv venv activate
uv pip install -e .
uv pip install -e ".[dev]"

使用 pip 的替代设置：

python -m venv venv
source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate
pip install -e .
# 或者：
pip install -r requirements.txt
pip install -r requirements-dev.txt

配置环境：

cp .env.example .env
# Edit .env with your API keys

VS Code / DevContainer 开发

安装带有 Remote Containers 扩展的 VS Code
在 VS Code 中打开项目文件夹
当提示时，点击“在容器中重新打开”
devcontainer 将构建并打开，并安装所有依赖项

使用 Claude Desktop 开发容器

将环境文件传递给 docker compose：

# Modern Docker Compose V2 syntax
docker compose --env-file .env up -d

在你的 Claude Desktop 配置中添加以下内容：

{
    "mcpServers": {
        "image-recognition": {
            "command": "docker",
            "args": [
                "exec",
                "-i",
                "mcp-image-recognition-dev",
                "python",
                "-m",
                "image_recognition_server.server"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

本地测试你的更改

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

# Install the MCP Inspector if you haven't already
npm install -g @modelcontextprotocol/inspector

# Start the server with the Inspector
npx @modelcontextprotocol/inspector mcp-image-recognition

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

与 Claude Desktop 集成进行测试

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

{
    "mcpServers": {
        "image-recognition": {
            "command": "python",
            "args": [
                "-m", "image_recognition_server.server"
            ],
            "cwd": "/path/to/your/mcp-image-recognition",
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

重启 Claude Desktop 以应用更改
通过上传图像或在对话中提供图像 URL 来进行测试

运行测试

运行所有测试：

run.bat test

运行特定测试套件：

run.bat test server
run.bat test anthropic
run.bat test openai

Docker 支持

构建 Docker 镜像：

docker build -t mcp-image-recognition .

运行容器：

docker run -it --env-file .env mcp-image-recognition

Docker 文件访问限制

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

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

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

映射本地目录到 Docker

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

{
    "mcpServers": {
        "image-recognition": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-v", "/path/on/host:/path/in/container",
                "zudsniper/mcp-image-recognition:latest"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

例如，要映射你的 Downloads 文件夹：

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

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

许可证

MIT License - 详见 LICENSE 文件。

使用 Cloudflare Workers AI

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

登录 Cloudflare 控制台并选择您的账户。
转到 AI > Workers AI。
选择 Use REST API 并创建具有 Workers AI 权限的 API 令牌。
在您的 .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 助手一起使用

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

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

上传图片后的示例提示：

Please describe this image in detail.

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

What text appears in this image?

或

Is there any safety concern in this image?

发布历史

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 Request。

发布新版本

要发布新版本：

更新 pyproject.toml 和 setup.py 中的版本号
将更改推送到 release 分支
GitHub Actions 将自动执行以下操作：
- 运行测试
- 构建并推送 Docker 镜像
- 发布到 PyPI
- 创建一个 GitHub 发布版

CI/CD 所需的仓库密钥：

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

工具列表

describe_image: Describe an image from base64-encoded data. Use for images directly uploaded to chat. Best for: Images uploaded to the current conversation where no public URL exists. Not for: Local files on your computer or images with public URLs. Args: image: Base64-encoded image data prompt: Optional prompt to guide the description Returns: str: Detailed description of the image
describe_image_from_file: Describe an image from a local file path. Requires proper file system access. Best for: Local files when the server has filesystem access to the path. Limitations: When using Docker, requires volume mapping (-v flag) to access host files. Not recommended for: Images uploaded to chat or images with public URLs. Args: filepath: Absolute path to the image file prompt: Optional prompt to guide the description Returns: str: Detailed description of the image
describe_image_from_url: Describe an image from a public URL. Most reliable method for web images. Best for: Images with public URLs accessible from the internet. Advantages: Works regardless of server deployment method (local/Docker). Not for: Local files or images already uploaded to the current conversation. Args: url: Direct URL to the image (must be publicly accessible) prompt: Optional prompt to guide the description Returns: str: Detailed description of the image

服务配置

[{'mcpServers': {'image-recognition': {'args': ['mcp-image-recognition'], 'command': 'uvx', 'env': {'OPENAI_API_KEY': 'your-api-key', 'OPENAI_MODEL': 'gpt-4o', 'VISION_PROVIDER': 'openai'}}}}, {'mcpServers': {'image-recognition': {'args': ['-m', 'image_recognition_server.server'], 'command': 'python', 'cwd': '/path/to/your/mcp-image-recognition', 'env': {'OPENAI_API_KEY': 'your-api-key', 'OPENAI_MODEL': 'gpt-4o', 'VISION_PROVIDER': 'openai'}}}}]

来源

来源：github
链接：https://github.com/mario-andreschak/mcp-image-recognition