图像描述 MCP 服务器

这是一个使用 xAI 的 Grok API 提供基于人工智能的图像分析的 Model Context Protocol (MCP) 服务器。

目的

此 MCP 服务器提供了一个安全接口，使 AI 助手能够利用 Grok 的先进视觉能力来分析图像。它支持网络托管的图像和本地文件，提供详细的描述、技术元数据提取以及光学字符识别（OCR）。

特性

当前实现

• describe_image_url - 分析来自网络 URL 的图像，并提供由 AI 生成的描述
• describe_image_file - 分析本地图像文件，并提供由 AI 生成的描述
• extract_text_from_image - 执行 OCR 以从图像中提取可读文本

预备条件

• 启用了 MCP Toolkit 的 Docker Desktop
• Docker MCP CLI 插件 (docker mcp 命令)
• 从 https://console.x.ai/ 获取的 Grok API 密钥

安装

请参阅随附文件中的逐步安装说明。

使用示例

在 Grok4 Code Fast 中，你可以询问：

• "描述这张图片：https://example.com/image.jpg"
• "这张本地图片显示了什么：/path/to/image.png"
• "从这张图片中提取任何文本：https://example.com/document.jpg"
• "给我这张照片的详细分析：https://example.com/photo.jpg"
• "你能在这张截图中读到什么文字：https://example.com/screenshot.png"

本地测试

# 设置环境变量用于测试
export GROK_API_KEY="your-grok-api-key"

# 直接运行
python image-description-mcp_server.py

# 测试 MCP 协议
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python image-description-mcp_server.py

添加新工具

1. 在 image-description-mcp_server.py 中添加函数
2. 使用 @mcp.tool() 装饰器
3. 更新目录条目，包含新的工具名称
4. 重新构建 Docker 镜像

故障排除

认证错误

• 使用 docker mcp secret list 验证密钥
• 确保 GROK_API_KEY 设置正确
• 在 https://console.x.ai/ 检查 API 密钥的有效性

图像处理错误

• 确保图像 URL 可访问且有效
• 检查本地文件路径是否存在且可读
• 验证图像格式受支持（JPEG、PNG、WebP 等）

安全注意事项

• 所有密钥存储在 Docker Desktop 密钥中
• 不要硬编码 API 密钥
• 在 Docker 中以非 root 用户身份运行
• 图像临时在内存中处理
• 不永久存储图像数据
• 不记录敏感数据

API 文档

此服务与 xAI 的 Grok API 集成：

• Grok API 参考文档：https://docs.x.ai/docs/api-reference
• MCP SDK 文档：https://github.com/modelcontextprotocol/sdk

数据来源

外部图像 URL

• 来源：通过 HTTP/HTTPS 访问的网络托管图像
• 访问方法：使用 httpx 的 HTTP GET 请求
• 目的：从任何公共 URL 下载图像进行分析
• 限制：仅限可访问的 URL；不包括受保护的图像

本地图像文件

• 来源：对本地图像文件的文件系统访问
• 访问方法：Python 文件 I/O
• 目的：分析用户系统上存储的本地图像
• 支持路径：绝对和相对文件路径
• 支持格式：JPEG、PNG、WebP、TIFF、GIF、BMP

Grok API

• 来源：具有视觉能力的 xAI Grok 模型
• 访问方法：通过 httpx 的 REST API 调用
• 目的：基于 AI 的图像分析和描述生成
• 数据流：图像转换为 base64，发送给 Grok，接收结构化分析

图像处理

• 来源：PIL (Pillow) 和 OpenCV 库
• 访问方法：本地处理
• 目的：提取技术元数据并执行 OCR
• 无外部调用：纯本地处理

许可证

MIT 许可证