Image Description MCP Server
A Model Context Protocol (MCP) server that provides AI-powered image analysis using xAI's Grok API.
Purpose
This MCP server provides a secure interface for AI assistants to analyze images using Grok's advanced vision capabilities. It supports both web-hosted images and local files, offering 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 descriptionsdescribe_image_file- Analyzes local image files and provides AI-generated descriptionsextract_text_from_image- Performs OCR to extract readable text from images
Prerequisites
- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (
docker mcpcommand) - Grok API key from https://console.x.ai/
Installation
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
- Add the function to
image-description-mcp_server.py - Decorate with
@mcp.tool() - Update the catalog entry with the new tool name
- Rebuild the Docker image
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 stored in Docker Desktop secrets
- Never hardcode API keys
- Running as non-root user in Docker
- Images processed temporarily in memory
- No permanent storage of image data
- Sensitive data 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 converted to base64, sent to Grok, 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
Metadata
Release files for iflow-mcp_7etsuo_image-description-mcp-server 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_7etsuo_image_description_mcp_server-0.1.1.tar.gz | 544.7 kB | Without provenance | Details for iflow_mcp_7etsuo_image_description_mcp_server-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_7etsuo_image_description_mcp_server-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_7etsuo_image_description_mcp_server-0.1.1-py3-none-any.whl |
Total release size: 1.1 MB
Release files / iflow_mcp_7etsuo_image_description_mcp_server-0.1.1.tar.gz
| Download URL | iflow_mcp_7etsuo_image_description_mcp_server-0.1.1.tar.gz |
|---|---|
| Size | 544.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
824503095b058636c7b81c54686346e218166612033c51b71ef0862c216a0b7a
|
|
BLAKE2b-256 checksum How to use checksums |
62b65c7cd29bc7da6004ad11c38bf6dc402a2b22f3f4804f57901f6b1b270481
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_7etsuo_image_description_mcp_server-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_7etsuo_image_description_mcp_server-0.1.1-py3-none-any.whl |
|---|---|
| Size | 550.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ea05771ab49c62db075b8bdc6a48ef57d788bf59d7c8dd1164d555a3aee43b1a
|
|
BLAKE2b-256 checksum How to use checksums |
9965c1893b7aad89f5c9ab56d6838df69113cdb8bad5147698555d5414f1c617
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_7etsuo_image-description-mcp-server 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.