# Read Image MCP

`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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

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

Supported source types:

- `path`
- `url`
- `base64`
- `data_url`

`structured` mode supports:

```json
{
  "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

```bash
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.