How do I use page-vision-mcp?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

page-vision-mcp

by 666666999999666

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Page Vision MCP

Structured visual analysis pipeline for coding agents — give your AI agent the ability to see.

PyPI Python License: MIT

中文文档

What It Does

Page Vision MCP turns visual analysis from a prompt into a tool. Instead of asking an LLM to "look at this image," your coding agent calls a structured API that returns consistent, machine-readable results with coordinates.

The Problem: AI coding agents modify frontend code but can't verify the result. They guess effects from source code alone.

The Solution: Screenshot → VLM Analysis → Structured JSON with coordinates → Agent makes informed decisions.

5 Tools:

Tool	What It Does	VLM	Playwright
`capture_page`	Screenshot a webpage (fallback)	-	Yes
`analyze_ui`	Structured UI analysis with region-level localization	Yes	-
`compare_ui`	Screenshot diff with mode constraints	Yes	-
`extract_text`	Block-level OCR with coordinates	Yes	-
`crop_analyze`	Progressive crop refinement with depth guards	Yes	-

3 Resources: vision://health | vision://version | vision://models

Related MCP server: pagelens

Pipeline

Screenshot ──> analyze_ui ──> Structured JSON
                  │
                  ├── Need detail? ──> crop_analyze (depth +1)
                  ├── Need text?   ──> extract_text
                  └── Need diff?   ──> compare_ui

Typical workflow:

"Check this page" ──> capture_page ──> analyze_ui ──> Agent finds issue
                                                          │
                                                    Agent fixes code
                                                          │
                               capture_page ──> compare_ui ──> Verified ✓

Quick Start

Install

pip install page-vision-mcp

# Optional: Playwright for screenshot fallback
pip install "page-vision-mcp[playwright]"
playwright install chromium

Configure

Set environment variables in your MCP client config (recommended) or create a .env file (see .env.example):

VISION_API_KEY=your-api-key
VISION_BASE_URL=https://api.openai.com/v1
VISION_MODEL_ID=gpt-4o

Works with any OpenAI-compatible VLM: GPT-4o, GLM-4V, Qwen-VL, etc.

MCP Client Config

Add to your MCP client configuration (Claude Code, Trae, Cursor, etc.):

{
  "mcpServers": {
    "page-vision-mcp": {
      "command": "page-vision-mcp",
      "env": {
        "VISION_API_KEY": "your-api-key",
        "VISION_BASE_URL": "https://api.openai.com/v1",
        "VISION_MODEL_ID": "gpt-4o"
      }
    }
  }
}

See examples/mcp_config.json for the full configuration with all options.

Tool Details

`analyze_ui` — UI Analysis

analyze_ui(
    image_source="screenshot.png",  # URL/path/base64/data_url
    prompt="",                       # optional focus
    task="ui",                       # ui/screenshot/qa/general
    detail="high"                    # low/auto/high
)

Returns structured observations with region-level localization (page → section → component → text), inferences, uncertainties, and suggested regions for further analysis.

Example output:

{
  "status": "success",
  "result": {
    "summary": "A dashboard with navigation bar, sidebar, and content area",
    "observations": [
      {"type": "component", "text": "Top navigation bar with 3 menu items", "bbox": [0.0, 0.0, 1.0, 0.08]},
      {"type": "issue", "text": "Menu items too close together", "bbox": [0.15, 0.02, 0.6, 0.07]}
    ],
    "suggested_regions": [
      {"description": "Menu overlap area", "bbox": [0.15, 0.02, 0.6, 0.07], "reason": "Text may overlap, zoom in"}
    ]
  }
}

`compare_ui` — Screenshot Diff

compare_ui(
    image_before="before.png",
    image_after="after.png",
    mode="viewport",     # viewport/fullpage/component
    focus="changes"      # changes/layout/text/colors/general
)

Returns structured differences (added/removed/modified/moved) with coordinates. Perfect for verifying code changes.

`extract_text` — OCR

extract_text(
    image_source="screenshot.png",
    language="auto",        # auto/chinese/english/japanese/korean
    preserve_layout=True
)

Returns text blocks with type, confidence, and bounding box coordinates. Preserves original language.

`crop_analyze` — Progressive Refinement

crop_analyze(
    image_source="screenshot.png",
    x=0.15, y=0.02, width=0.6, height=0.07,  # normalized 0.0-1.0
    depth=1,       # agent-managed, max 3
    task="ui"
)

Use coordinates from analyze_ui's suggested_regions. Max depth 3 prevents infinite recursion.

`capture_page` — Screenshot Fallback

capture_page(
    url="http://localhost:3000",
    viewport_width=1280,
    viewport_height=720,
    full_page=False,
    wait_for="networkidle"  # networkidle/domcontentload/load/none
)

Note: If your agent has built-in browser capability (Computer Use, Trae browser, Playwright MCP), use that instead and pass the screenshot path to analyze_ui.

Response Format

All tools return a structured JSON envelope:

{
  "status": "success",
  "tool": "analyze_ui",
  "result": { ... },
  "warnings": []
}

Configuration

Variable	Default	Description
`VISION_API_KEY`	-	VLM API key (required)
`VISION_BASE_URL`	`https://api.openai.com/v1`	VLM API endpoint
`VISION_MODEL_ID`	`gpt-4o`	Model to use
`VISION_TIMEOUT`	`60`	Request timeout (seconds)
`VISION_MAX_RETRIES`	`3`	Max retry attempts
`VISION_ALLOW_LOCAL_FILES`	`true`	Allow local file paths
`VISION_ALLOWED_PATHS`	-	Allowed directories (comma-separated)
`VISION_BLOCK_PRIVATE_IPS`	`true`	Block SSRF to private IPs
`VISION_MAX_IMAGE_SIZE_MB`	`10`	Max image size
`VISION_MAX_IMAGE_PIXELS`	`40000000`	Max pixel count

Security

SSRF Protection: Private IP addresses are blocked by default (VISION_BLOCK_PRIVATE_IPS)
Path Restriction: Local file access can be restricted to allowed directories (VISION_ALLOWED_PATHS)
Image Limits: Max image size and pixel count prevent resource exhaustion

Development

pip install -e ".[dev]"
pytest tests/

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

UI VerifyA
io.github.igrlk
Visual testing for coding agents: your agent sees every UI change it makes and triages each diff.
Testing & QA Tools CI/CD & DevOps
118
https://uiverify.ai/mcp
CaptureOneAI Web PerceptionA
com.captureoneai
Give agents eyes on any web page: structured context, and changes explained in plain language.
Browser Automation Web Scraping
61
https://captureoneai.com/mcp
ReconstructB
dev.reconstruct
Captured web interfaces, screenshots, flows and structured evidence for AI coding agents.
Design Tools Developer Tools Testing & QA Tools
701
https://reconstruct.dev/mcp
TheDesignAgentA
ai.thedesignagent
A design agent in your coding agent's loop: briefs each screen, reviews UX and visual quality.
Design Tools Developer Tools Agent Orchestration
1
https://www.thedesignagent.ai/mcp

Related MCP Servers

websight
Browser Automation Testing & QA Tools
h34tsink
A
license
Not graded
quality
D
maintenance
Enables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.
Updated 8 months ago (2026-03-07 17:47 UTC)
8 npm
MIT
pagelens
Browser Automation Testing & QA Tools Developer Tools
amoghmanral
A
license
Not graded
quality
D
maintenance
Enables AI coding agents to visually interact with frontend apps by taking screenshots, clicking elements, reading console logs, and performing visual diffs.
Updated 9 months ago (2026-02-09 03:00 UTC)
7 npm
3
MIT
vision-mcp
AI & Machine Learning Image & Video Processing
Pelican0126
A
license
A
quality
C
maintenance
Gives text-only coding agents the ability to 'see' images, videos, and screenshots by routing them to a vision model and returning structured text.
Updated 4 months ago (2026-06-25 05:52 UTC)
8
28 npm
1
MIT
jev-eyes
Image & Video Processing AI & Machine Learning
LeddoEngano
A
license
Not graded
quality
C
maintenance
Enables text-only agents to perceive images locally by converting screenshots into structured OCR text and spatial layout state, with optional zero-shot labeling and an ask tool for model decisions.
Updated 2 months ago (2026-09-20 15:20 UTC)
1
MIT