JinDaGe - image-description-mcp

article

README

🚀 图像描述MCP服务器

本项目是一个模型上下文协议（MCP）服务器，借助xAI的Grok API提供人工智能驱动的图像分析功能。它为AI助手提供了一个安全的接口，使其能够利用Grok先进的视觉能力分析图像。

🚀 快速开始

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

✨ 主要特性

当前实现

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

📦 安装指南

请参考文件中提供的详细步骤说明进行安装。

前提条件

启用了MCP工具包的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

添加新工具

将函数添加到image-description-mcp_server.py中
使用@mcp.tool()进行装饰
使用新工具名称更新目录条目
重新构建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调用；目的：人工智能驱动的图像分析和描述生成；数据流：图像转换为base64，发送到Grok，接收结构化分析 | | 图像处理 | 来源：PIL（Pillow）和OpenCV库；访问方法：本地处理；目的：提取技术元数据并执行OCR；无外部调用：纯本地处理 |

📄 许可证

本项目采用MIT许可证。

image-description-mcp_server