Read Image

read-image-mcp is a stdio MCP server that lets agents without native vision ask an OpenAI-compatible vision model to read images.

It exposes one tool, read_image, with three modes:

• describe: general image description
• ocr: visible text and layout notes
• structured: JSON extraction with an optional question and optional JSON Schema

Run From GitHub With npx

Recommended MCP command:

{
  "command": "npx",
  "args": [
    "-y",
    "--package",
    "github:xiayangqun/Read-Image-MCP#main",
    "read-image-mcp"
  ],
  "env": {
    "READ_IMAGE_MCP_CONFIG": "/absolute/path/read-image-mcp.config.json"
  }
}

#main is a rolling GitHub dependency. Restarting a client does not guarantee that npm fetches the newest commit because npm may reuse its cache. If you need an immediate refresh, clear npm cache or temporarily reference a specific commit SHA.

Config

Create a config file:

{
  "default_profile": "default",
  "profiles": {
    "default": {
      "base_url": "https://api.example.com/v1",
      "api_key": "your-api-key",
      "model": "vision-model-name",
      "timeout_ms": 60000
    }
  }
}

Lookup order:

1. READ_IMAGE_MCP_CONFIG
2. read-image-mcp.config.json in the current working directory
3. ~/.config/read-image-mcp/config.json

If api_key is empty or omitted, no Authorization header is sent. This is useful for local OpenAI-compatible gateways.

MCP Client Examples

Claude Desktop, Cursor, Codex, and OpenCode all use the same basic stdio command shape:

{
  "mcpServers": {
    "read-image": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "github:xiayangqun/Read-Image-MCP#main",
        "read-image-mcp"
      ],
      "env": {
        "READ_IMAGE_MCP_CONFIG": "/absolute/path/read-image-mcp.config.json"
      }
    }
  }
}

This repository is xiayangqun/Read-Image-MCP.

Tool Input

{
  "source": {
    "type": "path",
    "value": "/absolute/path/image.png"
  },
  "mode": "describe"
}

Supported source types:

• path
• url
• base64
• data_url

structured mode supports:

{
  "source": {
    "type": "url",
    "value": "https://example.com/screenshot.png"
  },
  "mode": "structured",
  "question": "Which UI error is visible?",
  "schema": {
    "type": "object",
    "properties": {
      "error": { "type": "string" }
    },
    "required": ["error"],
    "additionalProperties": false
  }
}

Local Development

npm install
npm test -- --run
npm run typecheck
npm run build
node dist/index.js --help

The built dist/ directory is committed so npx --package github:...#main read-image-mcp can run directly from GitHub without client-side TypeScript compilation.