image-recognition-mcp

An MCP (Model Context Protocol) server that exposes a single tool, vlm_recognize, for running an OpenAI-compatible vision-language model on a local image with a natural-language prompt.

Tool

vlm_recognize

Parameter	Type	Required	Description
prompt	string	yes	Natural-language instruction, e.g. "extract all text in the image"
image_path	string	yes	Path to a local image (png/jpg/jpeg/gif/webp/bmp)

Returns the model's text response.

Configuration

Required env

Env	Purpose
API_KEY	Bearer token for the OpenAI-compatible API
MODEL	Model name, e.g. gpt-4o, glm-4v, etc.

Optional env

Env	Default	Purpose
OPENAI_BASE_URL	https://api.openai.com/v1	Base URL for any OpenAI-compatible endpoint

Install

Option A: npx (once published to npm)

// e.g. Claude Code's mcp config
"image-recognition-mcp": {
  "command": "npx",
  "args": ["-y", "image-recognition-mcp"],
  "env": {
    "API_KEY": "your_key",
    "OPENAI_BASE_URL": "https://api.openai.com/v1",
    "MODEL": "gpt-4o"
  }
}

Option B: local checkout

"image-recognition-mcp": {
  "command": "node",
  "args": ["/absolute/path/to/image_recognition_mcp/index.js"],
  "env": {
    "API_KEY": "your_key",
    "OPENAI_BASE_URL": "https://api.openai.com/v1",
    "MODEL": "gpt-4o"
  }
}

Or after npm link in this repo:

"image-recognition-mcp": {
  "command": "image-recognition-mcp",
  "env": { "API_KEY": "...", "MODEL": "..." }
}

Self-test

API_KEY=test-key MODEL=gpt-4o node index.js --self-test

Verifies the image-file → data-URL helper (extension check + MIME map) without making an API call.

Notes

• Reads files from the local filesystem only. No URL fetching.
• Image is sent as a base64 data URL inside the chat/completions request body. Large images will produce large requests — resize before sending if your provider has size limits.
• Errors from the VLM API are surfaced as tool-call errors (non-zero exit code on the tool result).