@winton979/vision-mcp

MCP server that exposes an analyze_image tool backed by an OpenAI-compatible vision LLM (GPT-4o, Qwen-VL, etc.).

What it does

Provides a single MCP tool analyze_image that accepts an image via:

• path — local file path
• url — public http(s) URL
• base64 — raw base64 string (with or without data: prefix)

and returns a text description from the configured vision model.

Prerequisites

• Node.js ≥ 18 (global fetch required)

Configuration

Set these environment variables when configuring the MCP server:

Variable	Required	Default	Description
VISION_BASE_URL	No	https://api.openai.com/v1	OpenAI-compatible API base URL
VISION_API_KEY	Yes	—	API key for the gateway
VISION_MODEL	No	gpt-4o	Vision model name

Claude Code setup

macOS / Linux

Add to ~/.claude.json or ~/.claude/.mcp.json:

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "@winton979/vision-mcp"],
      "env": {
        "VISION_BASE_URL": "<your-base-url>",
        "VISION_API_KEY": "<your-api-key>",
        "VISION_MODEL": "<your-model>"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "vision": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@winton979/vision-mcp"],
      "env": {
        "VISION_BASE_URL": "<your-base-url>",
        "VISION_API_KEY": "<your-api-key>",
        "VISION_MODEL": "<your-model>"
      }
    }
  }
}

Codex setup

macOS / Linux

Add to ~/.codex/config.toml:

[mcp_servers.vision-mcp]
type = "stdio"
command = "npx"
args = ["-y", "@winton979/vision-mcp"]
env = { VISION_BASE_URL = "<your-base-url>", VISION_API_KEY = "<your-api-key>", VISION_MODEL = "<your-model>" }

Windows

[mcp_servers.vision-mcp]
type = "stdio"
command = "npx"
args = ["-y", "@winton979/vision-mcp"]
env = { VISION_BASE_URL = "<your-base-url>", VISION_API_KEY = "<your-api-key>", VISION_MODEL = "<your-model>" }

Tool: analyze_image

Parameter	Type	Required	Description
path	string	one of three	Local file path to the image
url	string	one of three	Public http(s) URL of the image
base64	string	one of three	Raw base64 string
mime_type	string	No	Override MIME type (auto-detected)
prompt	string	No	What to ask the model (defaults to detailed description)
model	string	No	Override model per call
max_tokens	integer	No	Default 4096
temperature	number	No	Default 0.2
detail	string	No	low / high / auto
system	string	No	Optional system message

Local development

git clone https://github.com/winton979/vision-mcp.git
cd vision-mcp
npm install
npm run build

# Run smoke test
SMOKE_IMAGE=/path/to/test.png VISION_API_KEY=sk-... npm run smoke

License

MIT