Layout Detector MCP
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., "@Layout Detector MCP analyze this screenshot with the images in /assets"
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.
Layout Detector MCP
An MCP (Model Context Protocol) server that analyzes webpage screenshots to extract layout information. Given a screenshot and image assets, it finds where each asset appears and calculates spatial relationships - enabling AI assistants to rebuild layouts with proper semantic structure.
Quick Start
Install from GitHub
pip install git+https://github.com/katlis/layout-detector-mcp.gitOr clone and install locally
git clone https://github.com/katlis/layout-detector-mcp.git
cd layout-detector-mcp
pip install .Verify installation:
python3 -c "from layout_detector import server; print('OK')"Related MCP server: websight
Configuration
Add to your Claude Code MCP settings (~/.claude.json or project .claude/settings.json):
{
"mcpServers": {
"layout-detector": {
"command": "layout-detector-mcp"
}
}
}After adding the configuration, restart Claude Code and run /mcp to verify the server is connected.
The Problem
When an AI assistant looks at a screenshot, it can describe what it sees but cannot extract precise pixel measurements. This makes it difficult to accurately recreate layouts without human intervention or extensive trial-and-error.
The Solution
This MCP server uses computer vision (OpenCV template matching) to:
Find known assets - Locate images within a screenshot with pixel-perfect coordinates
Analyze relationships - Calculate angles, distances, and relative positions
Detect patterns - Identify radial, grid, stacked, sidebar, or freeform layouts
Enable semantic rebuilds - Provide structured data for modern CSS implementation
Tools
analyze_layout
Performs full layout analysis including pattern detection. This is the main tool you'll use.
Parameters:
screenshot_path(string, required): Absolute path to the screenshot imageasset_paths(array of strings, required): Absolute paths to asset images to findthreshold(number, optional): Match confidence 0-1, default 0.8
Returns:
{
"viewport": { "width": 900, "height": 650 },
"pattern": {
"type": "radial",
"confidence": 0.90
},
"radial": {
"center_x": 450,
"center_y": 250,
"center_element": "logo.gif",
"average_radius": 196
},
"elements": [
{
"asset_name": "planet1.gif",
"x": 628,
"y": 89,
"width": 62,
"height": 62,
"angle_degrees": 45.0,
"distance_from_center": 240
}
]
}find_assets_in_screenshot
Locates image assets within a screenshot without layout analysis.
Parameters:
screenshot_path(string, required): Path to the screenshot imageasset_paths(array of strings, required): Paths to asset images to findthreshold(number, optional): Match confidence 0-1, default 0.8
Returns:
{
"found": 5,
"total_assets": 6,
"matches": [
{
"asset_path": "/path/to/logo.png",
"asset_name": "logo.png",
"x": 350,
"y": 200,
"width": 200,
"height": 100,
"center_x": 450,
"center_y": 250,
"confidence": 0.95
}
]
}get_screenshot_info
Get basic screenshot dimensions.
Parameters:
screenshot_path(string, required): Path to the screenshot image
Returns:
{
"path": "/path/to/screenshot.png",
"width": 900,
"height": 650
}Supported Layout Patterns
Pattern | Description | Key Data Returned |
Radial | Elements arranged around a center point | Center element, angles, distances |
Grid | Elements in rows and columns | Row/column positions, gaps |
Stacked | Vertical sections (header/main/footer) | Section names, Y positions |
Sidebar | Two-column with narrow sidebar | Sidebar side, widths |
Freeform | No clear pattern | Raw X/Y coordinates |
Example Usage
Once configured, Claude Code can use these tools:
User: Rebuild this webpage screenshot using the images in /assets
Claude: I'll analyze the layout first using the layout detector.
[Calls analyze_layout tool]
The analysis shows:
- Viewport: 900x650px
- Pattern: Radial (90% confidence)
- Center element: logo.gif at (450, 250)
- 8 elements arranged around the center
- Average distance from center: 196px
I'll implement this using CSS with the logo centered and
other elements positioned using absolute positioning...Supported Image Formats
PNG
JPEG
GIF (including animated - uses first frame)
WebP
BMP
Troubleshooting
"No module named 'cv2'"
OpenCV isn't installed. Run:
pip install opencv-python-headlessMCP server not showing in /mcp
Check your settings file path is correct
Ensure the command path is absolute (for source installs)
Restart Claude Code after changing settings
Run
python3 test_install.pyto verify the package works
Low confidence matches
Try lowering the threshold parameter (default 0.8). Values between 0.6-0.7 may help with compressed or scaled images.
Development
# Install in editable mode with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Test installation
python3 test_install.pyRequirements
Python 3.11+
OpenCV (opencv-python-headless)
NumPy
Pillow
MCP SDK
License
MIT
Available Tools
3 toolsanalyze_layoutA
Analyze the layout of assets in a screenshot. Finds all assets, identifies the center/hero element, calculates relative positions (angle and distance from center), and detects the layout pattern (radial, grid, or freeform). Returns structured data for rebuilding the layout with semantic CSS.
Inputs: screenshot_path (required), asset_paths (required), threshold.
find_assets_in_screenshotA
Find known image assets within a screenshot. Uses template matching to locate each asset and return its position (x, y, width, height). Useful for determining where specific images appear in a webpage screenshot.
Inputs: screenshot_path (required), asset_paths (required), threshold.
get_screenshot_infoB
Get basic information about a screenshot image, including its dimensions (width and height in pixels).
Inputs: screenshot_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose with no ambiguity. analyze_layout focuses on layout analysis and pattern detection, find_assets_in_screenshot handles asset location via template matching, and get_screenshot_info provides basic image metadata. The descriptions clearly differentiate their functions, preventing misselection.
All tool names follow a consistent verb_noun pattern with snake_case throughout (analyze_layout, find_assets_in_screenshot, get_screenshot_info). The naming is predictable and readable, using descriptive verbs that align with each tool's action.
With 3 tools, the count is slightly low but reasonable for the server's purpose of layout detection and screenshot analysis. Each tool earns its place by covering distinct aspects (layout analysis, asset finding, metadata retrieval), though a few more tools might enhance coverage without feeling heavy.
The tool set covers core operations for layout detection and screenshot analysis, including analysis, asset location, and metadata retrieval. Minor gaps exist, such as no tools for modifying or generating layouts, but agents can work around this with the provided structured data for rebuilding layouts.
Maintenance
Related MCP Connectors
Desktop and mobile website screenshots plus page context for AI agents and automation workflows.
Website screenshots for AI agents: real Chrome, ad/cookie/chat blocking, bot-wall detection.
Captured web interfaces, screenshots, flows and structured evidence for AI coding agents.
Screenshot web pages, render HTML and diff captures, with images sized for vision models.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered visual analysis of webpages for UI/UX assessment, including screenshot capture, element detection, accessibility auditing, and comprehensive JSON reporting.1ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.MIT
- AlicenseAqualityCmaintenanceAnalyzes and extracts design tokens, assets, and layout from live websites to enable AI clients to faithfully replicate them, with tools for screenshotting, component inspection, and pixel-diff verification.1424 npm4MIT
- AlicenseNot gradedqualityBmaintenanceEyes for text-only LLMs: decodes screenshots into exact structured text (words, coordinates, sizes, colors) using pure-code CV and OCR. Enables text-only models to reason about UI layouts without vision models or VRAM usage.2MIT