mcp-six-eyes
mcp-six-eyes lets text-only AI agents understand images by calling vision tools that return plain text.
Analyze or describe one or more images (general Q&A, scene/UI context)
OCR text from screenshots, documents, and diagrams
Compare two or more images (before/after, A/B, variants)
Answer questions that reference images by label ("image 1", "both figures")
Inspect UI screenshots and multi-step flows for UX/accessibility issues
Read charts, plots, tables, dashboards, and explain diagrams/architecture
Extract structured JSON from forms, receipts, invoices, and labels
Accept images via local path, file://, http(s), data URL, or base64
Support multiple vision providers (OpenAI, Anthropic, Gemini, OpenRouter, custom)
Cache vision results in memory to avoid repeat API costs
Check current provider/model configuration and limits with vision_status
Enables the MCP server to use Google Gemini's vision models for analyzing, describing, comparing, and extracting text from images.
Enables the MCP server to use OpenAI's vision-capable models for analyzing, describing, comparing, and extracting text from images.
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., "@mcp-six-eyes Describe this image: /path/to/photo.png"
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.
mcp-six-eyes
MCP server that gives text-only AI agents the ability to understand images, including multi-image chats like “refer image 1 and 2” or “compare these screenshots.”
Text-only models cannot see pixels. This server bridges that gap: agents call vision tools, the server talks to a multimodal API, and the agent gets plain text back.
Agent (text-only)
│ tool call: analyze / compare / refer / ocr / …
▼
mcp-six-eyes (this server)
│ 1..N images: path | URL | base64 (labels: 1, 2, before, …)
▼
Vision API (OpenAI / Anthropic / Gemini / OpenRouter / custom)
│
▼
Plain-text description / OCR / comparison / structured extract
│
▼
Agent continues reasoning with textWhy this works
MCP exposes tools an agent can call. The agent never needs native vision:
User uploads or points at one or more images
Agent calls a vision tool with those sources (and optional labels)
Server loads the image(s) and sends them to a multimodal model
Server returns only text, with stable image labels
The text-only agent uses that text like any other tool result
Related MCP server: MCP Vision Server
Tools
Tool | Purpose |
| General Q&A over one or more images |
| Dense scene/UI description (great “context dump” for agents) |
| Extract visible text (per-image sections when multi) |
| Diff 2+ images (before/after, A/B, variants) |
| Answer questions that cite “image 1”, “both figures”, etc. |
| UI/UX screenshot review and multi-step flows |
| Charts, plots, tables, dashboards |
| Architecture / flowchart / ERD / whiteboard explainers |
| Structured JSON from forms, receipts, tables, labels |
| Show configured provider/model and limits |
Image inputs
Every image tool accepts:
Single:
image: local path,file://,http(s), data URL, or base64Multi:
images: array of sources or{ source, label?, mimeType? }objectsYou can pass both; they are merged
Labels default to "1", "2", … so agent prompts like “compare image 1 and 2” map cleanly. Custom labels work too ("before", "after", "fig-a").
Optional detail: auto (default, longest edge ≤ VISION_MAX_IMAGE_EDGE), low (≤ 512), or original (no resize; still respects VISION_MAX_IMAGE_BYTES).
# one image
analyze_image({ image: "./shot.png", prompt: "What failed?" })
# multi-image with default labels 1..n
compare_images({
images: ["./a.png", "./b.png"],
prompt: "What changed in the error state?"
})
# multi-image with explicit labels (best for long threads)
refer_images({
images: [
{ source: "./login.png", label: "1" },
{ source: "./dashboard.png", label: "2" }
],
prompt: "Using image 1 and image 2, is the user authenticated?"
})Supported source forms:
local file path (
/path/to/image.pngorC:\path\to\image.png)file://URIhttp(s)URLdata URL (
data:image/png;base64,...)raw base64 (pass
mimeTypewhen possible)
Requirements
Node.js 20+
A vision-capable API key (OpenAI, Anthropic, Google, OpenRouter, or any OpenAI-compatible endpoint)
Install
Published on npm as mcp-six-eyes.
npx -y mcp-six-eyesOr install globally / as a project dependency:
npm install -g mcp-six-eyes
# or
npm install mcp-six-eyesMost people wire it into an MCP client instead of running it by hand. Example Claude Desktop / Cursor config:
{
"mcpServers": {
"mcp-six-eyes": {
"command": "npx",
"args": ["-y", "mcp-six-eyes"],
"env": {
"VISION_PROVIDER": "openai",
"OPENAI_API_KEY": "sk-..."
}
}
}
}Why npx is popular here:
no global install
client starts the server on demand
-yskips the install prompt on first runnpm caches the package for later launches
Local development
npm install
npm run buildThen either:
{
"mcpServers": {
"mcp-six-eyes": {
"command": "npx",
"args": ["-y", "."],
"env": {
"VISION_PROVIDER": "openai",
"OPENAI_API_KEY": "sk-..."
}
}
}
}or point Node at the built entrypoint:
{
"mcpServers": {
"mcp-six-eyes": {
"command": "node",
"args": ["./build/index.js"],
"env": {
"VISION_PROVIDER": "openai",
"OPENAI_API_KEY": "sk-..."
}
}
}
}Environment
Set provider keys in the MCP client env block (recommended) or a local .env for development.
Minimal OpenAI setup:
VISION_PROVIDER=openai
OPENAI_API_KEY=sk-...Optional model / limits:
VISION_MODEL=gpt-4o-mini
VISION_MAX_IMAGES=10
VISION_MAX_IMAGE_BYTES=20971520
VISION_MAX_IMAGE_EDGE=2048
VISION_CACHE_MAX_ENTRIES=200
VISION_RETRY_MAX_ATTEMPTS=3
VISION_BLOCK_PRIVATE_URLS=true
# VISION_ALLOWED_ROOTS= # unset = cwd + temp. Colon/semicolon/comma-separated.
# VISION_BLOCK_PRIVATE_URLS=false # only for a local-dev image server (localhost / LAN)The server speaks MCP over stdio. Do not write application logs to stdout.
VISION_BLOCK_PRIVATE_URLS defaults to true and rejects localhost, loopback, link-local, private IPv4/IPv6, and cloud metadata hosts, including after redirects. Set it to false only if you need to fetch from a local-dev image server such as http://127.0.0.1:3000/uploads/x.png.
VISION_ALLOWED_ROOTS limits local path and file:// reads. Unset uses process.cwd() plus the system temp directory (typical agent uploads). Separate entries with ;, ,, or : (Windows drive letters like C:\data are kept intact).
Caching
Vision calls are memoized by content, in memory. The cache key hashes the actual image bytes plus the task, prompt, labels, and token cap (not the source string), so a model that re-calls describe_image (or any vision tool) on the same image gets the previous answer back instantly, marked Cached: yes, without re-billing the vision API.
Default:
VISION_CACHE_MAX_ENTRIES=200(bounded, oldest evicted first)Set
VISION_CACHE_MAX_ENTRIES=0to disableFirst answer wins for a given key; a changed file or URL produces a new key
Failed and fallback responses are never cached (so a later retry can still use a recovered primary)
Cache lives only for the process lifetime (no disk persistence)
Client notes
Claude Desktop
Config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%AppData%\Claude\claude_desktop_config.json
Use the npx block from Quick start with npx.
Cursor
Add the same server block to .cursor/mcp.json (project) or your global Cursor MCP config.
Other stdio MCP hosts
Any host that can spawn:
npx -y mcp-six-eyesand pass environment variables will work.
Providers
Provider |
| Key env var | Default model |
OpenAI |
|
|
|
Anthropic |
|
|
|
Google Gemini |
|
|
|
OpenRouter |
|
|
|
Custom OpenAI-compatible |
|
| set |
Optional fallback:
VISION_FALLBACK_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...Example agent usage
Single screenshot
User: What's wrong in this screenshot? ./screenshots/build-error.png
Agent → ocr_image({ image: "./screenshots/build-error.png" })
Agent → analyze_image({
image: "./screenshots/build-error.png",
prompt: "Explain the error and suggest a fix"
})
Agent → answers in plain textMulti-image: refer / compare
User: I uploaded two shots. Compare image 1 and 2. Did the fix work?
Agent → compare_images({
images: [
{ source: "./before.png", label: "1" },
{ source: "./after.png", label: "2" }
],
prompt: "Did the red error banner disappear after the fix?"
})User: Refer image 1 and image 2. Which CTA is primary?
Agent → refer_images({
images: [
{ source: "./landing-a.png", label: "1" },
{ source: "./landing-b.png", label: "2" }
],
prompt: "Which image has the stronger primary CTA and why?"
})UI flow, chart, diagram, structured extract
inspect_ui({
images: ["./step1.png", "./step2.png", "./step3.png"],
prompt: "Describe the checkout flow and any friction"
})
read_chart({
image: "https://example.com/revenue.png",
prompt: "Summarize the trend and call out outliers"
})
explain_diagram({
image: "./architecture.png",
prompt: "List services and data flow"
})
extract_from_images({
image: "./receipt.jpg",
schema: "{\"merchant\":string,\"date\":string,\"total\":number,\"items\":[{\"name\":string,\"price\":number}]}"
})Architecture
src/
index.ts MCP server + tools
config.ts env/provider config
image.ts path/URL/base64 loader + multi-image labels
prompts.ts task prompts (analyze/describe/ocr/compare/...)
providers/
index.ts provider router + fallback
openai-compatible.ts OpenAI / OpenRouter / custom (multi-image)
anthropic.ts Claude vision (multi-image)
google.ts Gemini vision (multi-image)
types.ts shared contracts
test/ unit tests (node:test, mocked providers)
assets/
logo.png project logoDesign notes
Tools, not resources: image understanding is an action with side effects (API cost), so it is exposed as tools.
Text-only output: host models without vision only need text content blocks.
Labeled multi-image: agents in chat UIs talk about “image 1/2”; labels keep that grounding stable.
Task-specific tools: compare / refer / UI / chart / diagram / extract beat one mega-prompt for tool selection.
Stdio transport: simplest local integration for desktop agents.
No stdout logging: stdout is reserved for JSON-RPC; diagnostics go to stderr.
Provider abstraction: swap backends without changing tool names the agent learns.
Development
npm install
npm test
npm startScript | Purpose |
| Compile TypeScript to |
| Typecheck only |
| Build + full unit test suite |
| Run tests against current |
| Quick image-loader smoke script |
| Run MCP server on stdio |
Debug with the MCP Inspector:
npx @modelcontextprotocol/inspector node ./build/index.jsSee CONTRIBUTING.md for PR and coding guidelines.
Links
npm: mcp-six-eyes
Maintainer: rimunace
Release workflow
Maintainer path after local changes:
# one-time
npm login
# bump version + CHANGELOG, then ship
npm test
npm publish --access publicOptional helper (tests, then npm publish):
npm run releaseSecurity
API keys stay in environment variables / client config, never in tool responses
Remote URL fetches are explicit tool inputs; private/metadata URLs are blocked by default (
VISION_BLOCK_PRIVATE_URLS)Local paths and
file://URIs are limited toVISION_ALLOWED_ROOTS(cwd + temp when unset)Large images are rejected via
VISION_MAX_IMAGE_BYTES(default 20MB)Image count per call is capped via
VISION_MAX_IMAGES(default 10)detail=autodownscales PNG longest edge toVISION_MAX_IMAGE_EDGE(default 2048) before uploadThe response cache holds only content hashes and result text in memory; nothing is persisted to disk
Full policy: SECURITY.md.
Contributing
Issues and pull requests are welcome. Please run npm test before opening a PR and read CONTRIBUTING.md.
License
Available Tools
10 toolsanalyze_imageA
Analyze one or more images with a vision model and return plain text. Use for general Q&A when the host model cannot see images. Supports single image or multi images (image 1, image 2, ...).
Inputs: image, images, prompt, mimeType.
compare_imagesA
Compare two or more images and explain similarities/differences. Use for "compare image 1 and 2", before/after, A/B UI, design variants, or sequential screenshots.
Inputs: images (required), image, prompt, mimeType.
describe_imageA
Produce a detailed textual description of one or more images so a text-only model can reason about them. Prefer for general scene/UI understanding and multi-upload context dumps.
Inputs: image, images, prompt, mimeType.
explain_diagramA
Explain architecture diagrams, flowcharts, sequence diagrams, ERDs, UML, whiteboards, and similar figures for a text-only agent.
Inputs: image, images, prompt, mimeType.
extract_from_imagesA
Extract structured data (JSON) from one or more images: forms, receipts, IDs, tables, invoices, labels. Optional schema steers field names.
Inputs: image, images, prompt, schema, +1 more.
inspect_uiA
Inspect UI screenshots: layout, components, states, copy, errors, and likely UX/accessibility issues. Accepts one screen or a multi-step flow.
Inputs: image, images, prompt, mimeType.
ocr_imageA
Extract readable text from one or more images (screenshots, documents, diagrams, error dialogs). Multi-image calls return a section per image label.
Inputs: image, images, prompt, mimeType.
read_chartA
Read charts, graphs, plots, tables, and dashboards. Extracts axes, series, trends, and key values (marks estimates when exact pixels are unclear).
Inputs: image, images, prompt, mimeType.
refer_imagesA
Answer a question that refers to specific uploads by label ("refer image 1 and 2", "only the second screenshot", "both figures"). Grounds every claim in image labels.
Inputs: images (required), prompt (required), image, mimeType.
vision_statusA
Show which vision provider/model this MCP server is configured to use, plus image limits.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes: general Q&A, description, OCR, comparison, UI inspection, chart reading, diagram explanation, and structured extraction. Some overlap exists between analyze_image, describe_image, and refer_images, but their descriptions clarify the intended use cases, so agent confusion is unlikely.
The naming convention is largely verb_noun (analyze_image, compare_images, inspect_ui, read_chart, explain_diagram, extract_from_images). Minor deviations include vision_status (noun_noun) and ocr_image (acronym as verb), but the pattern is readable and predictable overall.
With 10 tools, the server is well-scoped for an image analysis domain. Each tool addresses a distinct need, and the count is within the ideal 3-15 range for a focused MCP server.
The tool surface covers general image Q&A, detailed description, OCR, comparison, labeled references, UI inspection, chart reading, diagram explanation, and structured data extraction—no obvious dead ends or missing essential operations for an image understanding server.
Maintenance
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for Qwen Image 3 AI image generation
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server that analyzes images with Google's Gemini vision models, allowing agents to describe or ask questions about images without bloating context.1MIT
- FlicenseNot gradedqualityDmaintenanceA versatile MCP server that adds vision capabilities (image analysis, OCR, image/video generation) to AI models lacking native vision, with support for multiple providers and automatic task routing.-
- AlicenseAqualityDmaintenanceEnables non-vision LLMs to analyze images via any OpenAI-compatible vision API. Hardened against truncation, empty responses, and timeouts for reliable analysis.135 npmMIT
- AlicenseAqualityDmaintenanceA drop-in MCP vision server for Zhipu GLM Coding Plan, offering 8 vision tools powered by glm-5v-turbo with smart retry and caching.870 npm1MIT