vision-mcp
The vision-mcp server enables text-only AI coding CLIs to "see" and reason about images by proxying them to Groq's vision model and returning text descriptions. It offers the following tools (each available as both a file path-based and clipboard-based variant):
Analyze images (
analyze_image/analyze_image_from_clipboard): Get a general description of any image or ask a specific question about it.OCR (
extract_text_from_screenshot): Extract text verbatim from screenshots of code editors, terminals, or documents.Error diagnosis (
diagnose_error_screenshot): Analyze error messages, stack traces, or crash dialogs and suggest causes and fixes.Technical diagram understanding (
understand_technical_diagram): Interpret architecture diagrams, flowcharts, UML, or ER diagrams and explain their components and relationships.Data visualization analysis (
analyze_data_visualization): Extract key values, trends, and insights from charts, graphs, or dashboards.UI description (
describe_ui): Describe a UI screenshot's layout, components, and style, with an option to generate a JSX/HTML+CSS sketch.
Supports common image formats (.png, .jpg, .jpeg, .gif, .webp, .bmp), file-based images up to ~3MB, and clipboard images up to 25MB.
Click on "Install 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., "@vision-mcpdiagnose this error screenshot: ./error.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.
vision-mcp
An MCP (Model Context Protocol) stdio server that gives text-only AI coding CLIs — Claude Code, Cline, OpenCode, Cursor, or anything else that speaks MCP — the ability to "see" images. It proxies image files to Groq's free vision model (Llama 4 Scout) and returns a text description, so the calling assistant can reason about screenshots, diagrams, error dialogs, and UI mockups even when its own model has no multimodal capability.
Security & privacy warning
Images you pass to these tools are sent to Groq's API (a third-party service) for processing. Do not use this tool on images containing secrets, credentials, API keys, or other sensitive personal data unless you accept that risk. This server does not add its own sandboxing beyond validating that the target file is a genuine image (see Limits below) — it runs with the same filesystem permissions as the process that launches it (your AI CLI), which already has full filesystem access on your machine. The server never logs image bytes, base64 payloads, or your API key. The *_from_clipboard tools read whatever image is currently on the OS clipboard and never write it to disk — the bytes stay in memory only, on their way to the same Groq API call.
Related MCP server: llm-vision-mcp
Prerequisites
Node.js 20 or later
A free Groq API key from console.groq.com/keys
Clipboard tool prerequisites
Only needed if you want to use the *_from_clipboard tools — the path-based tools (analyze_image, etc.) need none of this.
OS | Requirement | Install |
macOS |
|
|
Linux (Wayland) |
|
|
Linux (X11) |
|
|
Windows | none — uses built-in PowerShell | — |
Install & build
npm install
npm run buildConfigure your MCP client
Add an entry to your MCP client's server config (exact file location varies by client — see your CLI's docs):
{
"mcpServers": {
"vision-mcp": {
"command": "node",
"args": ["/absolute/path/to/vision-mcp/dist/index.js"],
"env": {
"GROQ_API_KEY": "gsk_your_key_here"
}
}
}
}Restart your AI CLI after adding this config.
OpenCode
OpenCode uses a different config schema (mcp instead of mcpServers, and environment instead of env). Add this to opencode.json (project root) or ~/.config/opencode/opencode.json (global):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vision-mcp": {
"type": "local",
"command": ["node", "/absolute/path/to/vision-mcp/dist/index.js"],
"enabled": true,
"environment": {
"GROQ_API_KEY": "gsk_your_key_here"
}
}
}
}Non-multimodal models in OpenCode (e.g. Build/Big Pickle) will say they "can't read images" when you paste a screenshot, even with vision-mcp installed — they don't know to reach for the tool on their own. Add a rule so the agent does this automatically: append to your project's AGENTS.md (or ~/.config/opencode/AGENTS.md for a global rule covering every project):
## Images
The current model cannot read images natively. Whenever an image is pasted,
attached, or referenced (including clipboard screenshots), immediately use
the matching vision-mcp tool (e.g. `analyze_image_from_clipboard`,
`diagnose_error_screenshot_from_clipboard`) instead of saying you can't see
images. Do not ask the user for permission first.Tools
Tool | Purpose | Params |
| General description of an image, or answer a specific question about it |
|
| OCR — verbatim text extraction from code/terminal/document screenshots |
|
| Analyze a screenshot of an error/stack trace/crash dialog → likely cause & fix |
|
| Read architecture diagrams, flowcharts, UML, or ER diagrams |
|
| Read charts/dashboards, extract key values and insights |
|
| Describe a UI screenshot's layout/components/style; ask for code to get a JSX/HTML+CSS sketch |
|
| Same as |
|
| Same as |
|
| Same as |
|
| Same as |
|
| Same as |
|
| Same as |
|
Example: ask your AI CLI "use diagnose_error_screenshot on ./error.png, I was running npm test" and it will call the tool with image_path: "./error.png" and context: "running npm test". Or, after copying a screenshot to the clipboard: "use diagnose_error_screenshot_from_clipboard, I was running npm test".
image_path may be absolute or relative — relative paths are resolved against the server process's working directory (normally your project root, as launched by your MCP client).
Limits
Allowed formats:
.png .jpg .jpeg .gif .webp .bmp, verified by file content (magic bytes), not just the extension. This applies equally to clipboard images.Max local file size: 20MB (path-based tools only, checked via
stat()before reading).Clipboard images can't be
stat()-ed before reading, so instead they're bounded by a 25MB raw ceiling enforced on the underlying OS command's output.Effective size for the vision model: Groq's API only allows ~4MB for inline base64 images (its 20MB limit applies only to hosted image URLs, which this server does not use). In practice, keep images under ~3MB raw so they encode under that 4MB base64 cap — larger images (whether from a file or the clipboard) are rejected before any API call is made, with a clear message.
Troubleshooting
"GROQ_API_KEY environment variable is not set" — add
GROQ_API_KEYto theenvblock in your MCP client config and restart the client."IMAGE_TOO_LARGE_FOR_MODEL" — resize or compress the image below ~3MB and try again.
"MAGIC_BYTE_MISMATCH" — the file's actual content doesn't match a supported image format (e.g. a non-image file with an image-like extension); this is a deliberate safety check, not a bug.
"UNSUPPORTED_EXTENSION" — convert the file to one of the allowed formats.
"NO_TOOL" (clipboard tools only) — the required OS clipboard utility isn't installed; see Clipboard tool prerequisites.
"NO_IMAGE" (clipboard tools only) — the clipboard doesn't currently hold an image; copy a screenshot/image first and try again.
"CLIPBOARD_IMAGE_TOO_LARGE" (clipboard tools only) — the clipboard image exceeds the 25MB raw ceiling; copy a smaller image.
"NO_DISPLAY" (Linux clipboard tools only) — no graphical session was detected (
WAYLAND_DISPLAY/DISPLAYboth unset); clipboard access needs a desktop session."UNSUPPORTED_PLATFORM" (clipboard tools only) — the clipboard tools only support macOS, Linux, and Windows.
Platform coverage notes
Clipboard support is implemented for macOS (pngpaste), Linux (wl-paste for Wayland, xclip for X11, with automatic fallback between them), and Windows (built-in PowerShell). It has been live-tested end-to-end on Linux/Wayland; the X11 and macOS/Windows code paths are written defensively per each tool's documented behavior but have not been exercised on real X11/macOS/Windows machines yet — treat those three as needing a follow-up manual smoke test before relying on them in production.
Available Tools
6 toolsanalyze_data_visualizationAnalyze Data VisualizationB
Read a chart, graph, or dashboard screenshot and extract key values, trends, and insights.
| Name | Required | Description | Default |
|---|---|---|---|
| question | No | Optional specific question about the chart/dashboard data. | |
| image_path | Yes | Path to the image file (absolute, or relative to the server's working directory). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must bear full burden. It states 'Read' implying non-destructive operation but does not disclose limitations (e.g., supported formats, accuracy, or whether it returns raw data vs. summary). Insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no fluff. Every word earns its place: verb, target, output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Purpose is clear but lacks behavioral details (e.g., return format, constraints) and no output schema. With no annotations, more context about what agents can expect would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (image_path and question). The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and specific resources 'chart, graph, or dashboard screenshot', and defines the output as 'extract key values, trends, and insights'. This distinguishes it from sibling tools like analyze_image (generic) or diagnose_error_screenshot (errors).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings such as 'analyze_image' or 'understand_technical_diagram'. The description implies use for data visualizations but does not provide when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
analyze_imageAnalyze ImageA
Describe an image or answer a specific question about it. General-purpose vision tool for when no more specific tool applies.
| Name | Required | Description | Default |
|---|---|---|---|
| question | No | Optional specific question about the image; if omitted, gives a general description. | |
| image_path | Yes | Path to the image file (absolute, or relative to the server's working directory). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It accurately states the tool describes or answers questions about images, but does not mention any limitations (e.g., file size, format support, accuracy, or response format). While not misleading, it lacks detail beyond the core function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only two short sentences with no redundant information. Every word adds value, and the key information (purpose and usage context) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is adequate. It covers the general use case and provides usage context. However, it could mention potential failure modes (e.g., unclear images) or the fact that it handles both description and question answering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal extra meaning: it clarifies that 'question' is optional and that the tool provides a general description if omitted. This is helpful but not substantial beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose ('Describe an image or answer a specific question about it') and explicitly distinguishes it from specialized siblings by labeling it as a 'General-purpose vision tool for when no more specific tool applies.' This provides specific verb+resource and differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'for when no more specific tool applies,' which gives clear guidance on when to use this tool versus the specialized alternatives listed in sibling tools. However, it does not explicitly state when not to use it or list conditions that would make a more specific tool preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describe_uiDescribe UIA
Describe a UI screenshot's layout, components, and style. Ask for code/markup to also get a JSX/HTML+CSS sketch.
| Name | Required | Description | Default |
|---|---|---|---|
| question | No | Optional focus, e.g. 'describe layout only' or 'give me a Tailwind/JSX sketch of this component'. | |
| image_path | Yes | Path to the image file (absolute, or relative to the server's working directory). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially carries the burden. It reveals the tool's output (description plus optional code) but does not confirm it is read-only, describe any side effects, or mention rate limits. The behavioral traits are implied but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The main action is front-loaded, and the optional behavior is added concisely. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should specify output format. It mentions 'description' and 'sketch' but does not clarify if the output is plain text or structured. Also, it could provide more context on image path requirements (e.g., supported formats). Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how to use the 'question' parameter to request code generation ('Ask for code/markup to also get a JSX/HTML+CSS sketch'). This aids correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'describe' and specific resource 'UI screenshot', covering layout, components, and style. It also distinguishes from sibling tools like 'analyze_data_visualization' by focusing on UI, making it easy to select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit when-to-use or when-not-to-use guidance. It does not compare with siblings or mention alternatives. The only hint is the phrase 'UI screenshot', which implicitly limits usage but is not sufficient for clear decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
diagnose_error_screenshotDiagnose Error ScreenshotA
Analyze a screenshot of an error message, stack trace, or crash dialog and suggest the cause and a fix.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Optional context: what you were doing when the error occurred, language/framework, etc. | |
| image_path | Yes | Path to the image file (absolute, or relative to the server's working directory). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool analyzes and suggests, but does not disclose limitations, output format, or processing characteristics. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence efficiently conveys the purpose and scope. No unnecessary words; all information serves the function. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should clarify what the tool returns. It mentions 'suggest the cause and a fix' but not whether output is plain text, structured JSON, or something else. Slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description adds no significant meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'analyze', the resource 'screenshot of an error message, stack trace, or crash dialog', and the outcome 'suggest the cause and a fix'. It effectively distinguishes from sibling tools like 'analyze_image' or 'extract_text_from_screenshot'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for error screenshots but provides no explicit when-to-use or when-not-to-use guidance. Alternatives among siblings are not mentioned, so the agent must infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
extract_text_from_screenshotExtract Text From ScreenshotB
OCR a screenshot (code, terminal output, or a document) and return the text verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Optional hint about what kind of text this is, e.g. 'terminal output' or 'code editor'. | |
| image_path | Yes | Path to the image file (absolute, or relative to the server's working directory). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool performs OCR and returns text verbatim, implying it is read-only and non-destructive. However, it does not detail behavior on invalid input, failure modes, or any side effects, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence containing the core action, resource, and examples. It is concise with no unnecessary words, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 parameters, no output schema, no annotations), the description covers the core purpose adequately but lacks details on return format or error handling. It is minimally complete but could be enhanced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, as both parameters have descriptions in the input schema. The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (OCR) and the resource (screenshot), with examples of suitable content (code, terminal output, document). It effectively conveys the tool's primary function, though it does not explicitly differentiate from siblings like 'analyze_image' or 'describe_ui'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs. alternatives (e.g., 'analyze_image', 'describe_ui'). It implies usage from the examples but does not state when not to use it or offer clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
understand_technical_diagramUnderstand Technical DiagramB
Read an architecture diagram, flowchart, UML, or ER diagram and explain its components and relationships.
| Name | Required | Description | Default |
|---|---|---|---|
| question | No | Optional specific question, e.g. 'What does service X call?' | |
| image_path | Yes | Path to the image file (absolute, or relative to the server's working directory). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the tool 'reads' and 'explains', but does not mention any constraints (e.g., image format, clarity requirements), side effects, or return format. This is minimal beyond purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single 14-word sentence, front-loaded with the verb 'Read'. Every word is meaningful, and there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain what the tool returns (e.g., a textual explanation) and mention any limitations. It only says 'explain its components and relationships', which is vague. The tool is simple (2 params) but still incomplete for an agent to fully understand the behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both parameters have descriptions in the schema. The tool description adds no additional meaning or context for the parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Read' and 'explain', the resource 'technical diagrams' (architecture, flowchart, UML, ER diagram), and the outcome 'components and relationships'. It distinguishes from siblings like analyze_data_visualization (data charts) and describe_ui (UI elements) by specifying diagram types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for technical diagrams by listing types, but provides no explicit when-to-use or when-not-to-use guidance nor comparison to sibling tools. The agent must infer usage from the listed types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v0.1.0- First observed
analyze_data_visualization - First observed
analyze_image - First observed
describe_ui - First observed
diagnose_error_screenshot - First observed
extract_text_from_screenshot - First observed
understand_technical_diagram
TDQS
Scored across 6 tools
Each tool targets a specific image understanding task (charts, general, UI, errors, OCR, diagrams) with no overlap, ensuring agents can easily select the right one.
All tools follow a consistent verb_noun pattern with clear, descriptive names like analyze_data_visualization and extract_text_from_screenshot, making the set predictable.
With 6 tools, the server is well-scoped for a general vision assistant, covering common image analysis needs without being bloated or sparse.
The tool set covers major vision tasks (description, OCR, diagrams, errors, UI, data viz), though advanced manipulation or more niche domains are absent. Minor gap.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
MCP server for Grok Imagine AI video generation
MCP server for Qwen Image 3 AI image generation
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseAqualityAmaintenanceA portable image-understanding MCP server that lets agents analyze local images, URLs, or base64 images via an OpenAI-compatible vision model.131072MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables any LLM to describe images from file paths, URLs, or base64 data by forwarding them to a supported vision provider such as OpenAI, Anthropic, or local Ollama models.62410MIT
- AlicenseAqualityAmaintenanceA Python MCP server that gives vision capabilities to text-only LLMs by exposing an analyze_image tool that sends local images to a vision-capable Ollama model and returns textual descriptions.1MIT
- 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.-