Image Description MCP Server

🚀 Image Description MCP Server

A Model Context Protocol (MCP) server that leverages xAI's Grok API to offer AI-driven image analysis.

🚀 Quick Start

This MCP server offers a secure interface for AI assistants to analyze images with Grok's advanced vision capabilities. It supports both web - hosted images and local files, providing detailed descriptions, technical metadata extraction, and optical character recognition (OCR).

✨ Features

Current Implementation

• describe_image_url - Analyzes images from web URLs and provides AI - generated descriptions.
• describe_image_file - Analyzes local image files and provides AI - generated descriptions.
• extract_text_from_image - Performs OCR to extract readable text from images.

📦 Installation

Prerequisites

• Docker Desktop with MCP Toolkit enabled.
• Docker MCP CLI plugin (docker mcp command).
• Grok API key from https://console.x.ai/.

Steps

See the step - by - step instructions provided with the files.

💻 Usage Examples

In Grok4 Code Fast

You can ask:

• "Describe this image: https://example.com/image.jpg"
• "What does this local image show: /path/to/image.png"
• "Extract any text from this image: https://example.com/document.jpg"
• "Give me a detailed analysis of this photo: https://example.com/photo.jpg"
• "What text can you read in this screenshot: https://example.com/screenshot.png"

Local Testing

# Set environment variables for testing
export GROK_API_KEY="your-grok-api-key"

# Run directly
python image-description-mcp_server.py

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

Adding New Tools

1. Add the function to image-description-mcp_server.py.
2. Decorate with @mcp.tool().
3. Update the catalog entry with the new tool name.
4. Rebuild the Docker image.

📚 Documentation

Troubleshooting

Authentication Errors

• Verify secrets with docker mcp secret list.
• Ensure GROK_API_KEY is set correctly.
• Check API key validity at https://console.x.ai/.

Image Processing Errors

• Ensure image URLs are accessible and valid.
• Check local file paths exist and are readable.
• Verify image formats are supported (JPEG, PNG, WebP, etc.).

Security Considerations

• All secrets are stored in Docker Desktop secrets.
• Never hardcode API keys.
• Run as a non - root user in Docker.
• Images are processed temporarily in memory.
• No permanent storage of image data.
• Sensitive data is never logged.

API Documentation

This service integrates with xAI's Grok API:

• Grok API Reference: https://docs.x.ai/docs/api - reference
• MCP SDK Documentation: https://github.com/modelcontextprotocol/sdk

Data Sources

External Image URLs

• Source: Web - hosted images accessible via HTTP/HTTPS.
• Access Method: HTTP GET requests using httpx.
• Purpose: Download images for analysis from any public URL.
• Limitations: Only accessible URLs; no authentication - protected images.

Local Image Files

• Source: Filesystem access to local image files.
• Access Method: Python file I/O.
• Purpose: Analyze images stored locally on the user's system.
• Supported Paths: Absolute and relative file paths.
• Supported Formats: JPEG, PNG, WebP, TIFF, GIF, BMP.

Grok API

• Source: xAI's Grok model with vision capabilities.
• Access Method: REST API calls via httpx.
• Purpose: AI - powered image analysis and description generation.
• Data Flow: Images are converted to base64, sent to Grok, and receive structured analysis.

Image Processing

• Source: PIL (Pillow) and OpenCV libraries.
• Access Method: Local processing.
• Purpose: Extract technical metadata and perform OCR.
• No External Calls: Pure local processing.

📄 License

MIT License