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

Returns the model's text response.

Related MCP server: image_mcp

Configuration

Required env

Optional env

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).