Skip to main content
Glama
Sign In
enesjakozh
MCP Image Recognition Server

MCP Image Recognition Server

by mario-andreschak
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP Image Recognition Server

An MCP server that provides image recognition capabilities using Anthropic and OpenAI vision APIs. Version 0.1.2.

Features

  • Image description using Anthropic Claude Vision or OpenAI GPT-4 Vision

  • Support for multiple image formats (JPEG, PNG, GIF, WebP)

  • Configurable primary and fallback providers

  • Base64 and file-based image input support

  • Optional text extraction using Tesseract OCR

Related MCP server: Image Parse MCP

Requirements

  • Python 3.8 or higher

  • Tesseract OCR (optional) - Required for text extraction feature

    • Windows: Download and install from UB-Mannheim/tesseract

    • Linux: sudo apt-get install tesseract-ocr

    • macOS: brew install tesseract

Installation

  1. Clone the repository:

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

  1. Create and configure your environment file:

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

  1. Build the project:

build.bat

Usage

Running the Server

Spawn the server using python:

python -m image_recognition_server.server

Start the server using batch instead:

run.bat server

Start the server in development mode with the MCP Inspector:

run.bat debug

Available Tools

  1. describe_image

    • Input: Base64-encoded image data and MIME type

    • Output: Detailed description of the image

  2. describe_image_from_file

    • Input: Path to an image file

    • Output: Detailed description of the image

Environment Configuration

  • ANTHROPIC_API_KEY: Your Anthropic API key.

  • OPENAI_API_KEY: Your OpenAI API key.

  • VISION_PROVIDER: Primary vision provider (anthropic or openai).

  • FALLBACK_PROVIDER: Optional fallback provider.

  • LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR).

  • ENABLE_OCR: Enable Tesseract OCR text extraction (true or false).

  • TESSERACT_CMD: Optional custom path to Tesseract executable.

  • OPENAI_MODEL: OpenAI Model (default: gpt-4o-mini). Can use OpenRouter format for other models (e.g., anthropic/claude-3.5-sonnet:beta).

  • OPENAI_BASE_URL: Optional custom base URL for the OpenAI API. Set to https://openrouter.ai/api/v1 for OpenRouter.

  • OPENAI_TIMEOUT: Optional custom timeout (in seconds) for the OpenAI API.

Using OpenRouter

OpenRouter allows you to access various models using the OpenAI API format. To use OpenRouter, follow these steps:

  1. Obtain an OpenAI API key from OpenRouter.

  2. Set OPENAI_API_KEY in your .env file to your OpenRouter API key.

  3. Set OPENAI_BASE_URL to https://openrouter.ai/api/v1.

  4. Set OPENAI_MODEL to the desired model using the OpenRouter format (e.g., anthropic/claude-3.5-sonnet:beta).

  5. Set VISION_PROVIDER to openai.

Default Models

  • Anthropic: claude-3.5-sonnet-beta

  • OpenAI: gpt-4o-mini

  • OpenRouter: Use the anthropic/claude-3.5-sonnet:beta format in OPENAI_MODEL.

Development

Running Tests

Run all tests:

run.bat test

Run specific test suite:

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

Docker Support

Build the Docker image:

docker build -t mcp-image-recognition .

Run the container:

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

License

MIT License - see LICENSE file for details.

Release History

  • 0.1.2 (2025-02-20): Improved OCR error handling and added comprehensive test coverage for OCR functionality

  • 0.1.1 (2025-02-19): Added Tesseract OCR support for text extraction from images (optional feature)

  • 0.1.0 (2025-02-19): Initial release with Anthropic and OpenAI vision support

Available Tools

3 tools
describe_imageA

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

Inputs: image (required), prompt.

describe_image_from_fileA

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

Inputs: filepath (required), prompt.

describe_image_from_urlA

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

Inputs: url (required), prompt.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose based on the image source: base64-encoded data, local file path, or public URL. The descriptions explicitly state what each tool is 'best for' and 'not for,' eliminating any ambiguity about when to use which tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun_from_source pattern (describe_image, describe_image_from_file, describe_image_from_url). This predictable naming makes it easy for an agent to understand the relationship between the tools and their specific use cases.

    Tool Count5/5

    With 3 tools, this server is well-scoped for its purpose of image recognition across different input methods. Each tool earns its place by covering a distinct scenario (uploaded images, local files, web URLs), making the set complete without being bloated.

    Completeness5/5

    The tool surface comprehensively covers all common ways to provide an image for description: base64 data, local files, and public URLs. There are no obvious gaps, as these three methods handle most practical use cases an agent would encounter in image recognition tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches