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., "@claude-vision-mcp Screenshot the current webpage at localhost:3000"
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.
A Model Context Protocol server that gives Claude Code the ability to see — capturing the screen, individual windows, screen regions, and live web pages, plus comparing screenshots for visual-regression checks.
Built so an AI coding agent can verify its own visual output: render a UI change, screenshot it, and look at the result instead of guessing.
Six tools, exposed over MCP via FastMCP:
capture_screen — screenshot the full screen or a specific display, with token-aware downscaling.
capture_window_tool — screenshot a single window by (partial, case-insensitive) title or app name.
capture_screen_region — screenshot an arbitrary rectangular region by coordinates.
capture_webpage_tool — screenshot any URL (including localhost dev servers) via a headless Playwright browser; supports full-page capture and waiting on a CSS selector.
compare_screenshots — diff two images and report the percentage and region of changed pixels (visual regression).
list_windows — list all open windows as Application | Window Title to find a capture target.
Related MCP server: MCP Screenshot Server
Python ≥ 3.10
macOS (window capture uses AppleScript; screen capture needs Screen Recording permission)
Dependencies: mcp[cli], Pillow, playwright, numpy
git clone https://github.com/wonderstone843/claude-vision-mcp.git
cd claude-vision-mcp
pip install -e .
playwright install chromium # only needed for capture_webpage_toolGrant Screen Recording permission to your terminal in System Settings → Privacy & Security → Screen Recording.
Register the server (stdio):
claude mcp add claude-vision -- claude-vision-mcpOr add it to your MCP config manually:
{
"mcpServers": {
"claude-vision": {
"command": "claude-vision-mcp"
}
}
}Then ask Claude to, e.g., "screenshot localhost:3000 and check the hero section renders," or "capture the Blender window."
claude_vision_mcp/
server.py # FastMCP server + the 6 tool definitions
capture.py # full-screen / window / region capture
windows.py # AppleScript window enumeration
browser.py # Playwright headless webpage capture
compare.py # pixel-diff comparisonMIT — see LICENSE.
Author: Joshua Penn
Capture a screenshot of the full screen or a specific display.
Parameters:
display: Display number (0 = all displays combined, 1 = main, 2 = secondary). Default 0.
max_size: Maximum pixel dimension for the largest side. Default 800. Smaller = faster + fewer tokens. Use 400 for quick checks, 1200 for detail.
Returns the screenshot as an Image. Requires Screen Recording permission in macOS System Settings.
| Name | Required | Description | Default |
|---|---|---|---|
| display | No | ||
| max_size | No |
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 discloses the Screen Recording permission requirement and explains the impact of max_size on speed and tokens. However, it does not clarify if the operation is read-only or destructive (it is read-only by nature), and does not mention error scenarios or side effects.
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 concise and well-structured: first sentence states purpose, then parameter explanations in a clear list format, ending with return type and permission note. No wasted content.
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), the description is fairly complete. It covers purpose, parameter semantics, return type, and a key requirement (permission). Minor gaps include format of the image and error handling, but these are not critical.
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 has 0% description coverage. The description adds significant meaning: explains display values (0=all, 1=main, 2=secondary) and max_size with usage advice (400 for quick, 1200 for detail). This compensates well for the missing schema descriptions.
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 captures a screenshot of the full screen or a specific display, using specific verbs and resource. However, it does not explicitly differentiate from sibling tools like capture_screen_region or capture_window_tool, though the purpose is implied by the name and context.
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 guidance is provided on when to use this tool versus its siblings (e.g., capture_screen_region for a region, capture_window_tool for a window). The description gives advice on max_size parameter values for quick checks vs. detail, but not for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a specific rectangular region of the screen.
Parameters:
x: Left edge coordinate in pixels (0 = left edge of screen).
y: Top edge coordinate in pixels (0 = top edge of screen).
width: Width of the region in pixels.
height: Height of the region in pixels.
max_size: Maximum pixel dimension for the output. Default 800.
Use capture_screen first to see the full screen and identify coordinates. Returns the captured region as an Image.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| width | Yes | ||
| height | Yes | ||
| max_size | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It mentions returning an Image and explains parameters, but lacks details like coordinate system scope (primary display only?) or permission requirements. Adequate but not thorough.
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 concise, front-loads the purpose, lists parameters clearly, and includes a usage tip. Every sentence is useful, no fluff.
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, description states return type (Image) adequately. Covers parameters and usage hint. Could mention if coordinates are screen-relative, but it's implied by '0 = left/top edge of screen'. Nearly complete.
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 0%, but description provides clear explanations for all 5 parameters including default for max_size. This adds significant value beyond the schema's just names and types.
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 'Capture a specific rectangular region of the screen', which is a specific verb+resource. It distinguishes from siblings like capture_screen (full screen) and capture_window (window).
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?
Explicitly advises to use capture_screen first to see the full screen and identify coordinates, providing clear context for when to use this tool. No exclusion statements, but the guidance is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a screenshot of a web page using a headless browser.
Useful for capturing local dev servers (localhost), web apps, or any URL. The browser launches on first use and stays running for subsequent captures.
Parameters:
url: The URL to capture (e.g., "http://localhost:3000", "https://example.com").
viewport_width: Browser viewport width in pixels. Default 1280.
viewport_height: Browser viewport height in pixels. Default 720.
max_size: Maximum pixel dimension for the output. Default 800.
full_page: If true, capture the entire scrollable page. Default false.
wait_for_selector: Optional CSS selector to wait for before capturing (e.g., "#main-content", ".loaded"). Leave empty to skip.
Returns the web page screenshot as an Image.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| max_size | No | ||
| full_page | No | ||
| viewport_width | No | ||
| viewport_height | No | ||
| wait_for_selector | No |
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 mentions that the browser launches on first use and stays running, which is helpful. However, it doesn't disclose potential behavioral traits like memory usage, rate limits, or failure modes (e.g., if the page times out).
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 well-structured: a concise introductory paragraph, followed by bullet points for each parameter. It is front-loaded with the main purpose. However, the parameter descriptions could be slightly more concise, and the overall length is justified by the lack of schema descriptions.
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 correctly states it returns an Image. It covers all 6 parameters, usage context (localhost, web apps), and behavioral note (browser staying running). The tool's purpose and parameters are fully explained, making it complete for agent invocation.
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 0%, so the description must compensate. It provides a detailed explanation for each parameter, including defaults and example values (e.g., 'url: The URL to capture (e.g., "http://localhost:3000")') and clarifies the purpose of each. This adds significant value 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 captures a screenshot of a web page using a headless browser. It specifies the resource (web page) and action (capture screenshot), and distinguishes from siblings like capture_screen (likely whole screen) and capture_window_tool. The mention of local dev servers adds specificity.
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 explicitly says 'Useful for capturing local dev servers (localhost), web apps, or any URL,' providing clear usage context. It doesn't explicitly state when not to use or alternatives, but the context implies use for web pages, and siblings are listed separately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a screenshot of a specific window by its title.
Searches for a window whose title contains the given text (case-insensitive). Also matches against application name. Use list_windows() first to see available windows.
Parameters:
window_title: Full or partial window title to match (e.g., "Firefox", "Terminal", "Blender"). Also matches application names.
max_size: Maximum pixel dimension for the largest side. Default 800.
Returns the screenshot as an Image. If no match is found, returns an error listing available windows.
| Name | Required | Description | Default |
|---|---|---|---|
| max_size | No | ||
| window_title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses matching behavior, default max_size, and error handling (returns error listing available windows if no match). It mentions return type as Image. However, it doesn't specify behavior on multiple matches or whether the window is brought to front, leaving minor gaps.
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 concise, well-structured, and front-loaded. It uses a few sentences to cover purpose, usage, parameters, and error behavior. Every sentence adds value with no fluff.
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 2 parameters, no output schema, and no annotations, the description covers the core functionality, parameter details, error handling, and relationship to list_windows. It is complete for an agent to select and invoke the tool correctly.
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 0%, but the description explains both parameters: window_title (full/partial, case-insensitive, matches app names) and max_size (max dimension, default 800). This adds significant meaning beyond the bare 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 'Capture a screenshot of a specific window by its title.' It uses a specific verb and resource, and distinguishes from sibling tools like capture_screen, capture_screen_region, and capture_webpage_tool. It also references list_windows as a complementary tool.
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?
Provides explicit guidance: 'Use list_windows() first to see available windows.' It explains matching behavior (case-insensitive, matches title and app name) and implies when to use this tool vs. siblings. No explicit 'when not to use' but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two screenshots and describe visual differences.
Analyzes pixel differences between two images and reports the percentage of changed pixels and the region of change.
Useful for:
Verifying UI changes after code edits
Checking before/after visual regression
Confirming rendering output differences
Parameters:
image_path_1: Absolute path to the first (baseline) image.
image_path_2: Absolute path to the second (comparison) image.
max_size: Maximum pixel dimension for analysis. Default 800.
Returns a text description of the differences found.
| Name | Required | Description | Default |
|---|---|---|---|
| max_size | No | ||
| image_path_1 | Yes | ||
| image_path_2 | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains that the tool analyzes pixel differences and returns a text description, including percentage and region of change. It implies no side effects, which is appropriate for a compare tool.
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 structured with a clear purpose statement, detailed behavior explanation, bulleted use cases, and parameter list. Every sentence is informative and there is no wasted text.
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?
The description explains what the tool does and returns, but does not detail the exact format of the text description (e.g., coordinates or just percentage). Since an output schema exists, this is acceptable, but a bit more specificity would improve completeness.
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?
With 0% schema description coverage, the description adds meaning for all three parameters: it explains image_path_1 as baseline, image_path_2 as comparison, and max_size as maximum pixel dimension with default 800. This compensates well for the schema's lack of descriptions.
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: 'Compare two screenshots and describe visual differences.' It specifies analyzing pixel differences and reporting percentage of changed pixels and region. This distinguishes it from sibling tools that capture screenshots.
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 a bulleted list of useful scenarios (UI changes, visual regression, rendering differences), giving clear context for when to use the tool. However, it does not explicitly mention when not to use it or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all open windows with their application names and titles.
Use this to find the correct window title before calling capture_window_tool. Returns a formatted list showing 'Application | Window Title' for each open window.
No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does not disclose behavioral traits beyond listing windows. It doesn't mention permissions, error cases, or performance implications, but for a simple read-only tool, the lack of detail is acceptable.
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 three short sentences, each serving a purpose: stating the action, providing usage guidance, and noting the absence of parameters. No unnecessary words.
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?
For this simple tool with no parameters and a clear output format described, the description is complete. It covers what the tool does, when to use it, and what to expect.
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?
No parameters exist, so baseline 4 applies. The description correctly notes no parameters are required, adding no false expectations.
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 lists all open windows with application names and titles. It distinguishes from sibling tools like capture_window_tool by focusing on enumeration rather than capture.
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?
Explicitly says to use this tool before capture_window_tool to find the correct window title, providing clear guidance on when and why to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0capture_screencapture_screen_regioncapture_webpage_toolcapture_window_toolcompare_screenshotslist_windowsScored across 6 tools
Each tool has a clearly distinct purpose: capturing different screen sources (full, region, webpage, window), comparing images, or listing windows. No overlapping functionality.
Most tools follow a 'capture_' prefix pattern, but capture_webpage_tool and capture_window_tool have an inconsistent '_tool' suffix, and compare_screenshots and list_windows use different verb forms.
6 tools is well-scoped for a vision capture server, covering core capture methods plus comparison and window listing without excess.
Covers all major capture scenarios (screen, region, window, webpage) and adds comparison and window listing. Minor gap: no tool to list displays or get screen dimensions, but all essential workflows are present.
Capture screenshots, detect visual regressions between page versions, and analyze with AI.
Screenshot, PDF and HTML-to-image rendering API so Claude and Cursor can see any web page.
Screenshot, PDF and HTML-to-image rendering API so Claude and Cursor can see any web page.
Screenshot any URL to PNG/JPEG. Cookie banners and chat widgets removed by default.
