Skip to main content
Glama

Codex Vision MCP

Codex Vision MCP is a local MCP server that adds computer-vision tools to coding agents and models that do not support native image input. It uses existing Codex OAuth credentials and calls the ChatGPT/Codex Responses backend.

The main use case is running a strong text/code model, such as GLM 5.2, while still giving the agent a way to inspect screenshots, diagrams, UI mockups, chart images, and local image files through MCP tools.

Name

Use Codex Vision MCP.

Vision MCP is too generic. The important differentiator is that this server uses Codex OAuth and the Codex Responses backend as the vision provider.

The package and executable names are:

  • package: codex-vision-mcp

  • command: codex-vision-mcp

  • suggested MCP server name: codex-vision

Related MCP server: multimodal-mcp

Tools

  • ui_to_artifact

  • extract_text_from_screenshot

  • diagnose_error_screenshot

  • understand_technical_diagram

  • analyze_data_visualization

  • ui_diff_check

  • analyze_image

  • analyze_video

Tool names are intentionally compatible with the Z.AI vision MCP tool shape so prompts and agent behavior can transfer easily.

How It Works

The MCP client calls one of the vision tools with a local file path, remote URL, or data:image/... URL. This server loads the image, sends it to the Codex Responses backend with Codex OAuth, and returns a text result to the calling agent.

This is useful when the active model is text-only or when the model provider rejects native image input.

Current Limitation

In Claude Code, pasting an image directly into the client does not automatically call this MCP server. Claude Code transcodes pasted images and sends them directly to the selected model. If the selected model does not support image input, the model call can fail before MCP tools are involved.

For now, use a local file path and ask the agent to inspect that file:

What does ./demo.png describe?

or:

Use codex-vision to analyze /absolute/path/to/demo.png

A future Claude Code integration can intercept pasted images before the model call, route them through this MCP server, and continue with a text-only prompt.

Install From Source

npm install
npm run build
node dist/index.js --smoke

--smoke checks Codex OAuth discovery and prints redacted auth metadata.

Add To Claude Code

Project-local registration is recommended. It keeps this vision server enabled only for the repository that needs it.

cd /path/to/your/project
claude mcp add --scope local codex-vision -- npx -y codex-vision-mcp

For local development from this checkout:

cd /path/to/your/project
claude mcp add --scope local codex-vision -- node /absolute/path/to/vision_mcp/dist/index.js

On Windows PowerShell:

cd C:\path\to\your\project
claude mcp add --scope local codex-vision -- npx -y codex-vision-mcp

Auth

Current auth discovery prioritizes local Codex auth first after explicit environment overrides:

  1. CODEX_VISION_AUTH_JSON

  2. CODEX_IMAGEN_AUTH_JSON

  3. CODEX_AUTH_JSON

  4. CODEX_HOME/auth.json

  5. ~/.codex/auth.json

The server refreshes near-expiry OAuth tokens through https://auth.openai.com/oauth/token and writes them back atomically.

Environment

  • CODEX_VISION_MODEL: Responses model, default gpt-5.5

  • CODEX_VISION_BASE_URL: default https://chatgpt.com/backend-api/codex

  • CODEX_VISION_AUTH_JSON: explicit auth JSON path

  • CODEX_VISION_IMAGE_DETAIL: auto, low, high, or original

  • CODEX_VISION_TIMEOUT_MS: default 300000

  • CODEX_VISION_MAX_IMAGE_MB: default 10

  • CODEX_VISION_MAX_VIDEO_MB: default 50

  • CODEX_VISION_VIDEO_FRAMES: default 4

  • CODEX_VISION_MCP_LOG_PATH: optional log file path

Platform Support

The server is implemented in Node.js and should run on macOS, Linux, and Windows with Node.js 22 or newer.

Cross-platform notes:

  • Local paths are resolved with Node path and os.homedir().

  • ~/.codex/auth.json maps to the current user's home directory on each OS.

  • Auth file permissions are tightened with chmod only on non-Windows systems.

  • The optional Codex CLI version lookup falls back safely if codex is not on PATH.

  • analyze_video requires ffmpeg on PATH; install ffmpeg separately on each OS or extract frames manually and use analyze_image.

This has been checked for obvious macOS-only assumptions in the source. Windows and Linux should work, but still need real-machine smoke testing.

Development

npm run check
npm run build

Run the server directly:

node dist/index.js

Available Tools

8 tools
analyze_data_visualizationAnalyze Data VisualizationA
Read-only

Analyze charts, graphs, dashboards, and other data visualizations to extract metrics, trends, anomalies, and recommendations.

Inputs: prompt (required), image_source (required), image_detail, analysis_focus. Returns: data, error, success, metadata

analyze_imageAnalyze ImageA
Read-only

General-purpose image analysis for cases not covered by the specialized tools. Use as a fallback for flexible visual understanding.

Inputs: prompt (required), image_source (required), image_detail. Returns: data, error, success, metadata

analyze_videoAnalyze VideoA
Read-only

Analyze a local or remote video by extracting sampled frames with ffmpeg and sending them to Codex vision analysis.

Requires ffmpeg on PATH. For precise video work, extract important frames manually and use analyze_image or ui_diff_check.

Inputs: prompt (required), video_source (required), frame_count, image_detail. Returns: data, error, success, metadata

diagnose_error_screenshotDiagnose Error ScreenshotA
Read-only

Diagnose screenshots of error messages, stack traces, exception dialogs, or failed command output.

Returns likely cause, actionable fixes, and prevention notes where possible.

Inputs: prompt (required), image_source (required), context, image_detail. Returns: data, error, success, metadata

extract_text_from_screenshotExtract Text From ScreenshotA
Read-only

Extract and recognize text from screenshots, including code, terminal output, logs, documentation, and UI copy.

Use when the user needs faithful OCR or text reconstruction from an image.

Inputs: prompt (required), image_source (required), image_detail, programming_language. Returns: data, error, success, metadata

ui_diff_checkUI Diff CheckB
Read-only

Compare an expected/reference UI screenshot with an actual/current UI screenshot and report visual implementation differences.

Inputs: prompt (required), actual_image_source (required), expected_image_source (required), image_detail. Returns: data, error, success, metadata

ui_to_artifactUI To ArtifactA
Read-only

Convert UI screenshots into artifacts: frontend code, AI prompts, design specifications, or natural-language descriptions.

Use only for UI screenshots. Do not use for OCR-only screenshots, error messages, diagrams, or charts.

Inputs: prompt (required), output_type (required), image_source (required), image_detail. Returns: data, error, success, metadata

understand_technical_diagramUnderstand Technical DiagramA
Read-only

Analyze technical diagrams including architecture diagrams, flowcharts, UML, ER diagrams, network diagrams, and sequence diagrams.

Inputs: prompt (required), image_source (required), diagram_type, image_detail. Returns: data, error, success, metadata

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools target distinct visual domains (charts, UI, diagrams, errors) with clear descriptions. The fallback analyze_image could overlap but is explicitly a catch-all. Only extract_text_from_screenshot and diagnose_error_screenshot have slight boundary ambiguity, but usage notes clarify.

    Naming Consistency4/5

    All names use lowercase snake_case and a verb_noun or adjective_noun pattern. Some verbs vary (analyze, diagnose, extract, ui_diff_check, ui_to_artifact, understand), but the structure is predictable and readable.

    Tool Count5/5

    8 tools is well-scoped for a vision analysis server. Each tool addresses a specific common use case without overcrowding. The count is appropriate for the domain.

    Completeness4/5

    The tool set covers major vision tasks: general image/video analysis, UI comparison, error screenshots, text extraction, diagram understanding, and artifact generation. Minor gaps like object detection exist, but the set is comprehensive for typical developer workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      A lightweight MCP server that provides vision capabilities to text-only models like Claude Code and Codex by forwarding images to an OpenAI-compatible multimodal model, offering tools for image analysis and OCR.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides vision understanding capabilities such as image analysis, OCR, object localization, and video frame analysis, plus optional image generation and editing, to coding agents via OpenAI-compatible multimodal models. Runs as a local MCP server with HTTP and stdio transports, configurable for clients like Codex, Claude Code, Kimi, and Cursor.
      3
      23 npm
      MIT