Codex Vision MCP
Uses OpenAI's Codex/Responses backend to provide computer vision capabilities, enabling text-only agents to analyze images, screenshots, diagrams, and local files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex Vision MCP what does ./demo.png describe?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpcommand:
codex-vision-mcpsuggested MCP server name:
codex-vision
Related MCP server: multimodal-mcp
Tools
ui_to_artifactextract_text_from_screenshotdiagnose_error_screenshotunderstand_technical_diagramanalyze_data_visualizationui_diff_checkanalyze_imageanalyze_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.pngA 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-mcpFor 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.jsOn Windows PowerShell:
cd C:\path\to\your\project
claude mcp add --scope local codex-vision -- npx -y codex-vision-mcpAuth
Current auth discovery prioritizes local Codex auth first after explicit environment overrides:
CODEX_VISION_AUTH_JSONCODEX_IMAGEN_AUTH_JSONCODEX_AUTH_JSONCODEX_HOME/auth.json~/.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, defaultgpt-5.5CODEX_VISION_BASE_URL: defaulthttps://chatgpt.com/backend-api/codexCODEX_VISION_AUTH_JSON: explicit auth JSON pathCODEX_VISION_IMAGE_DETAIL:auto,low,high, ororiginalCODEX_VISION_TIMEOUT_MS: default300000CODEX_VISION_MAX_IMAGE_MB: default10CODEX_VISION_MAX_VIDEO_MB: default50CODEX_VISION_VIDEO_FRAMES: default4CODEX_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
pathandos.homedir().~/.codex/auth.jsonmaps to the current user's home directory on each OS.Auth file permissions are tightened with
chmodonly on non-Windows systems.The optional Codex CLI version lookup falls back safely if
codexis not onPATH.analyze_videorequiresffmpegonPATH; installffmpegseparately on each OS or extract frames manually and useanalyze_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 buildRun the server directly:
node dist/index.jsAvailable Tools
8 toolsanalyze_data_visualizationAnalyze Data VisualizationARead-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 ImageARead-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 VideoARead-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 ScreenshotARead-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 ScreenshotARead-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 CheckBRead-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 ArtifactARead-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 DiagramARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server for agentverse documentation, generated by doc2mcp.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseAqualityBmaintenanceA portable image-understanding MCP server that lets agents analyze local images, URLs, or base64 images via an OpenAI-compatible vision model.166MIT
- FlicenseAqualityDmaintenanceLocal MCP server that adds multimodal capabilities to text-only models like Codex/DeepSeek, offering tools for image description, audio transcription, video analysis, image/video generation, and speech synthesis.101-
- FlicenseNot gradedqualityBmaintenanceA 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.-
- AlicenseAqualityDmaintenanceProvides 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.323 npmMIT