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.

• Strict Security & Resource Bounds:

  • Built-in SSRF protection against unauthorized internal network scans (VISION_ALLOW_PRIVATE_NETWORK).

  • Safe local file access controlled via root path whitelisting (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" }

💻 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