openai-vision-mcp-server

GitHub Repository: https://github.com/ygq-future/openai-vision-mcp-server

A Model Context Protocol (MCP) stdio server for bounded, high-precision image analysis using OpenAI Chat Completions-compatible Vision APIs (e.g. OpenAI gpt-4o, Qwen VL, DeepSeek Vision, Local vLLM/Ollama, etc.).

✨ Features

• Multi-Source Image Inputs: Analyze images directly from file:// local paths, http:// / https:// URLs, or base64 raw data payloads.

• Smart Adaptive Tiling & Overview Pipeline: Automatically generates overview thumbnails and ordered overlapping detail tiles for high-resolution images, preserving visual detail without hitting token limits.

• Universal OpenAI Compatibility: Works with any API endpoint following the standard OpenAI /chat/completions vision protocol.

• Configurable Security & Resource Bounds:

  • Optional SSRF protection for public-network-only deployments (VISION_ALLOW_PRIVATE_NETWORK=false).

  • Optional local file root restrictions (VISION_ALLOWED_FILE_ROOTS).

  • Configurable ceilings for file size, decoded pixel count, HTTP timeouts, and max redirects.

• Clean Stdio Transport: Keeps stdout strictly isolated for standard MCP JSON-RPC protocol messages while outputting diagnostics to stderr without leaking credentials or payloads.

Related MCP server: mcp-vision-server

🚀 Quick Start

You can run openai-vision-mcp-server without manual installation using npx or bunx.

MCP Client Integration Examples

Add the server to your preferred MCP client's configuration file (e.g., Claude Desktop, Cursor, Windsurf, VS Code / Antigravity):

Standard claude_desktop_config.json / mcp.json:

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "openai-vision-mcp-server"],
      "env": {
        "VISION_BASE_URL": "https://api.openai.com/v1",
        "VISION_API_KEY": "your-api-key-here",
        "VISION_MODEL": "gpt-4o"
      }
    }
  }
}

⚙️ Environment Variables & Configuration

Configuration is passed entirely through environment variables defined in the MCP server configuration:

🛠 Available Tools

analyze_images

Analyzes single or multiple images using configured Vision models and produces structured analysis reports.

Input Schema

ImageSource Types

• File Source: { "type": "file", "uri": "file:///path/to/image.png", "label": "optional label" }

• URL Source: { "type": "url", "url": "https://example.com/photo.jpg", "label": "optional label" }

• Base64 Source: { "type": "base64", "data": "<base64_string>", "mediaType": "image/png", "label": "optional label" }

Results, warnings, and errors

A successful result includes complete. When complete is false, the answer may still contain useful evidence, but every warnings[] entry explains the missing coverage with these machine-readable fields:

{
  "code": "TILE_BUDGET_EXCEEDED",
  "message": "Detail coverage requires 16 tiles, but this call allows 10.",
  "retryable": false,
  "userActionRequired": true,
  "nextAction": "Continue with the partial result, disclose the missing coverage, and increase maxTiles only if the user requests complete analysis.",
  "details": { "requiredTiles": 16, "allowedTiles": 10 }
}

A failed Tool call returns isError: true, the same guidance as readable text, and structuredContent.error containing code, message, retryable, userActionRequired, nextAction, and optional safe details. The calling AI should follow nextAction: permanent input/configuration/protocol failures explicitly say not to retry, while transient network, timeout, rate-limit, and server failures allow one bounded caller retry. If the same transient failure repeats, stop and notify the user instead of looping.

Errors never include credentials, authorization headers, Base64/image bytes, upstream response bodies, complete local paths or URLs, stack traces, or full prompts.

💻 Local Development

This project uses Bun for fast testing and compilation.

# Install dependencies
bun install

# Run unit and integration tests
bun test

# Run code check (format, lint, typecheck, test, build)
bun run check

# Build output files
bun run build

📄 License

MIT License © 2026 ygq-future