Viewglass MCP
WZBbiao/viewglass-mcp
Inspeção e automação de UI iOS para agentes Claude
Ver no GitHubServidor MCP que expõe 15 ferramentas para inspeção e automação de UI iOS em tempo real. Permite que agentes de IA capturem snapshots, toquem elementos, façam scroll, digitalizem texto e validem estados de interface sem recompilação.
Instalação
npx convez-ai WZBbiao/viewglass-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Testes automatizados de fluxos iOS
- Validação visual de designs em dispositivos reais
- Automação de interações complexas em aplicativos iOS
- Debugging de interface através de agent AI
Veredito

Ferramenta especializada e bem-estruturada para automação de UI iOS com integração nativa em MCP. Requer conhecimento de iOS/Xcode, mas oferece leverage altíssimo para quem trabalha com desenvolvimento mobile.
README
A tradução para o português deste README ainda está na fila.
viewglass-mcp
MCP Server for Viewglass iOS UI inspection.
Exposes 15 tools for AI agents — bundles the viewglass CLI binary, no separate install required.
Install the Viewglass skill
Like xcodebuildmcp, ViewglassMCP works best when its skill is installed into the AI client skill directory and the project AGENTS.md is updated.
When ViewglassMCP starts normally, it now bootstraps itself automatically like xcodebuildmcp:
- installs the ViewglassMCP skill into detected client skill directories (for example
.claude/skillsand.agents/skills) - appends the Viewglass guidance line to the project
AGENTS.md - creates
.viewglassmcp/config.yaml,.viewglassmcp/README.md, and.viewglassmcp/recipes.yamlin the project root
viewglass-mcp init --force still exists as an explicit repair/bootstrap command, but it should not be required for the normal MCP path.
Tools
| Tool | Description |
|---|---|
ui_snapshot | Capture an agent-first UI snapshot with summary, navigation candidates, budgeted searchable nodes, matched recipes, and optional rawTree. |
ui_attr_get | Get runtime attributes of a node by OID. |
ui_tap | Tap a node by exact oid from ui_snapshot. Supports UIControl, gesture-backed views, UITableViewCell, and UICollectionViewCell. |
ui_scroll | Scroll by exact oid; resolves wrapper/cell targets to a real scroll view and performs a swipe-style scroll. |
ui_set_attr | Set an attribute on a node at runtime (live, no recompile). |
ui_invoke | Call any ObjC selector on any node — the highest-leverage tool. |
ui_wait | Poll until a node appears, disappears, or an attribute matches. |
ui_assert | Assert visibility, text, count, or attribute — fails as MCP error. |
ui_connect | Resolve and pin the active session to a specific app bundle id. |
ui_screenshot | Capture a PNG of the full screen or a specific node. |
ui_input | Type text into a UITextField / UITextView by exact oid from ui_snapshot and return an execution summary. |
ui_swipe | Swipe a node in a direction. |
ui_long_press | Long-press a node. |
ui_dismiss | Dismiss a presented view controller by exact oid from ui_snapshot and return an execution summary. |
compare_with_design | Screenshot device + return Figma URL for Vision diff. |
Recommended agent workflow
For page navigation, settings flows, tab switching, and custom UI:
- Start with
ui_snapshot- Default output is a small action index: visible labels, groups, navigation candidates, and likely action targets.
- For textless settings/profile icons, inspect
summary.navigationCandidatesandareaHintsuch astopRight. - Use
ui_screenshotfor visual layout andui_attr_getfor long text or detailed attributes after you know theoid. - Use
mode=fullIndexonly when the default action index is insufficient. - Treat it as the source of truth for "where am I right now?".
- Then use execution tools with exact
oid- Extract the exact target
oidfromui_snapshot.groupsorui_snapshot.nodes. ui_tap,ui_scroll,ui_input, andui_dismissall requireoid.- Prefer user-visible labels in the snapshot over UIKit private class guesses.
- Extract the exact target
- Use
ui_waitor anotherui_snapshotto verify transitions- Do not assume a tap has finished a navigation animation unless you verify it.
- Use
ui_attr_getonly after the correct node is known- This is for reading precise runtime values such as text color or font.
Avoid this pattern:
- guessing
UITabBar,UITabBarButton,UIButton, or private UIKit classes first - passing guessed labels to
ui_tapinstead of first locating an exactoidinui_snapshot - trying to infer the current page from repeated locator guesses instead of starting with
ui_snapshot - taking a screenshot before checking the structured snapshot, unless the task is explicitly visual
Project-local experience memory
For repeated flows, keep project-local experience under:
.viewglassmcp/README.md.viewglassmcp/recipes.yaml.viewglassmcp/config.yaml
These files are maintained by the agent after successful live runs.
Use config.yaml for stable project defaults like the app bundle identifier.
Use recipes.yaml for reusable target-finding recipes, not fragile runtime oid values.
Recommended config / recipe signals:
controllerHintsgroupRolesearchableTextAnyaccessibilityIdAnyclassHintsareaHintsuccess
Templates are included in this package under:
The bundled recipes.yaml is intentionally empty and generic. Agents should only write project-specific recipes after successful live runs in the current project.
templates/.viewglassmcp/README.mdtemplates/.viewglassmcp/recipes.yaml
Agent-first rule:
- the agent should create
.viewglassmcp/automatically inside the current project when a task is likely to repeat - after a reusable live task succeeds, the agent must update
.viewglassmcp/recipes.yamlin the same session before finishing the task - on later runs, the agent should consult
.viewglassmcp/recipes.yamlbefore fallback exploration
Requirements
- iOS app with ViewglassServer running (simulator or device).
- No other dependencies — the
viewglassCLI binary is bundled in this package.
Usage
Claude Desktop / any MCP client
If you installed the package globally, viewglass-mcp starts the MCP server by default and also supports viewglass-mcp init.
{
"mcpServers": {
"viewglass": {
"command": "npx",
"args": ["-y", "viewglass-mcp"]
}
}
}
Or install globally for faster startup:
npm install -g viewglass-mcp
{
"mcpServers": {
"viewglass": {
"command": "viewglass-mcp"
}
}
}
Session
All tools accept an optional session in bundleId@port format (e.g. com.example.App@47164).
If omitted, ViewglassMCP first checks .viewglassmcp/config.yaml for sessionDefaults.bundleId and prefers the matching running app. If no config match exists, it falls back to the first detected running app.
The agent should usually rely on this automatic resolution instead of trying to scan for sessions manually.
Override binary
Set VIEWGLASS_BIN to use a specific binary (development / CI):
VIEWGLASS_BIN=/path/to/viewglass npx viewglass-mcp
Debug logging
All logs go to stderr by default so they do not corrupt the MCP stdout protocol stream.
VIEWGLASS_MCP_LOG=1 npx viewglass-mcp
Optional flags:
VIEWGLASS_MCP_LOG_TOOL=1: log each tool call start/end summaryVIEWGLASS_MCP_LOG_CLI=1: log each internalviewglassCLI command, duration, and exit statusVIEWGLASS_MCP_LOG_FILE=/tmp/viewglass-mcp.log: write logs to a file instead ofstderrVIEWGLASS_MCP_LOG_SPLIT_BY_SESSION=1: whenVIEWGLASS_MCP_LOG_FILEis set, write one file per session
Export the latest contiguous run from a session log into a replay-oriented flow draft:
npm run export:flow -- /tmp/viewglass-mcp.log.com.example.app@47175.log
Optional flags:
-- --all-runs: export every detected run in the log file-- --include-screenshots: keep screenshot steps in the draft-- --gap-ms 120000: change the run split threshold
Initialize project-local experience memory in a target project:
There is no required bootstrap command. The agent should create and maintain .viewglassmcp/ automatically.
When session logging is enabled, each line includes session=<bundleId@port> when the tool/CLI call has one.
With file splitting enabled, examples look like:
/tmp/viewglass-mcp.log.com.example.app@47175.log/tmp/viewglass-mcp.log.com.example.app@47164.log
Development
npm install
npm run build # compile TypeScript
npm test # unit tests (Vitest)
E2E tests
- Start your iOS simulator with ViewglassServer enabled.
- Update
SESSIONinsrc/__tests__/e2e.ts. - Run:
VIEWGLASS_BIN=/path/to/viewglass npm run test:e2e
Architecture
src/
runner.ts # CLI runner, binary resolution, injectable ExecFn
index.ts # MCP Server — registers all 16 tools
tools/
ui_snapshot.ts ui_attr_get.ts
ui_tap.ts ui_scroll.ts ui_set_attr.ts
ui_invoke.ts ui_wait.ts ui_assert.ts
ui_scan.ts ui_screenshot.ts ui_input.ts
ui_swipe.ts ui_long_press.ts ui_dismiss.ts
compare_with_design.ts
__tests__/
*.test.ts # unit tests (mock ExecFn injection)
e2e.ts # e2e tests against live simulator
bin/ # bundled viewglass CLI binaries (not in git, in npm)
viewglass-darwin-arm64
viewglass-darwin-x64
.viewglass-cli-version # pins the CLI version bundled in this release
Binary resolution order: VIEWGLASS_BIN env → viewglass in $PATH → bin/ bundled binary.