VisualQ MCP Server
The VisualQ MCP Server provides a comprehensive QA and visual testing platform for web projects, covering visual/functional regression testing, audits, run monitoring, and CI integration.
Project & Scenario Management
List projects, check setup health (identify blockers/warnings), list VRT scenarios (labels, URLs, viewports), and get full scenario configuration details.
Visual Regression Testing (VRT)
Run VRT comparisons against baselines, capture new baselines, list failed scenarios with mismatch percentages, get detailed diff stats, explain VRT failures with structured analysis and recommended actions, approve results to promote to baselines (
confirm: true), and create comparison rules (ignore, dynamic, layout-only) (confirm: true).
Functional Regression Testing (FRT)
Run FRT feature test suites (
confirm: true).
Run Monitoring
Get run status/summary, poll for run completion, view run history, and compare metrics between two runs.
Quality & Audit Reports
Get composite quality scores with pillar breakdowns, plus detailed performance, SEO, accessibility, and analytics tracking plan reports.
GitHub / CI Integration
Post or update VRT summary comments on GitHub PRs (
confirm: true) to gate pull requests based on quality.
Note: All mutating actions (approving results, creating rules, running FRT, posting PR comments) require explicit confirm: true.
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., "@VisualQ MCP Server Run visual regression test on the login page"
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.
@visualq/mcp
MCP server for VisualQ — the Quality OS agent interface. @visualq/mcp exposes 44 tools (qa profile): multi-pillar audit, VRT/FRT (frt_get_feature), tracking plan + JIRA proof, rolling health. For Cursor, Claude Desktop, or any MCP client.
Production setup (recommended)
Sign in to https://visualq.ai
Go to Settings → Agent API Keys (org admin)
Create a key with scope
mcp_fullOptionally set a default project slug if you mostly work on one client
Copy the Cursor MCP config snippet
Paste into
~/.cursor/mcp.json(or project.cursor/mcp.json) and restart Cursor
Or one command:
npx @visualq/setup-agent cursor --key vq_org_live_… --project my-siteOr install the Cursor plugin (skills + rules bundled).
{
"mcpServers": {
"visualq": {
"command": "npx",
"args": ["-y", "@visualq/mcp"],
"env": {
"VISUALQ_API_KEY": "vq_org_live_…",
"VISUALQ_BASE_URL": "https://visualq.ai",
"VISUALQ_TOOL_PROFILE": "qa"
}
}
}
}Single-project shortcut
If your org key has a default project (or you set it only in MCP env):
"VISUALQ_DEFAULT_PROJECT": "afp-com"Then tools can omit project when the key has defaultProject on the server or this env var is set in the MCP config.
Multi-project orgs
Pass project on every tool call (slug or id), e.g. "project": "afp-com".
Related MCP server: @capsulate/mcp
Environment variables
Variable | Required | Default | Description |
| yes | — | Org agent key |
| no |
| VisualQ instance (use your origin for self-hosted) |
| no | — | Default project slug injected into tool args |
| no |
|
|
| no | — | Set |
| no |
| HTTP mode port |
API key scopes
Scope | MCP read | MCP write ( | CI |
| yes | no | no |
| yes | yes | no |
| no | no | yes |
Org agent keys support mcp_read and mcp_full only.
Typical agent workflows
Quality MCP PR gate: gate_pr_quality → fix with explain_vrt_failure / frt_heal_step_def → run_vrt or run_full_audit
Onboard a site: create_project → crawl_site → create_scenario → run_baseline → create_frt_scenario → run_frt_feature
Full QA: run_full_audit (optional pillars[]) → wait_for_run → gate_pr_quality → get_site_health
Pillar-only audit: run_full_audit with pillars: ["a11y"], ["tracking"], etc.
Pre-merge VRT: list_scenarios → run_vrt → get_run_failures → explain_vrt_failure
FRT in CI: GitHub Action type: frt or visualq frt --api-key …
Jira tracking proof: read ticket → tracking_prove_jira_ticket with confirm: true (semantic intent → generic linked scenario) → paste jiraMarkdown into JIRA.
Jira-driven QA: read ticket → create_scenario / create_frt_scenario with ticket id in name → run tests
Mutating tools require confirm: true in arguments.
Legacy project CI key
For GitHub Actions / Jenkins, use a project-scoped key (vq_live_…) with scope ci — not the org agent key.
{
"mcpServers": {
"visualq": {
"command": "npx",
"args": ["-y", "@visualq/mcp"],
"env": {
"VISUALQ_API_KEY": "vq_live_…",
"VISUALQ_BASE_URL": "https://visualq.ai"
}
}
}
}Create in Project → Settings → API keys.
Hosted REST gateway (advanced)
VisualQ also exposes JSON invoke (not stdio MCP wire protocol):
GET https://visualq.ai/api/mcp— tool catalog (public)POST https://visualq.ai/api/mcp/v1/invoke—X-API-Key+{ "tool", "args" }
The @visualq/mcp npm package is the supported IDE integration path.
Local development
npm install
npm run build
VISUALQ_API_KEY=vq_org_live_… VISUALQ_BASE_URL=http://localhost:3000 node dist/index.jsSync tool manifest from the visualq backend (sibling repo):
cd ../visualq && npm run mcp:export-manifest
cd ../visualq-mcp && npm run sync-manifestBefore publishing to npm:
cd ../visualq && npm run mcp:export-manifest
cd ../visualq-mcp && npm test && npm run build && npm run sync-manifest
npm publish --access public
# Optional: publish agent skills if skills/ changed
cd packages/agent-skills && npm publish --access publicRepository
Package: abecms/visualq-mcp
Backend: abecms/visualq (
/api/mcp/v1/invoke)
Available Tools
22 toolsa11y_get_reportD
Latest accessibility audit report.
Inputs: project.
approve_vrt_resultsB
Approve failed VRT results and promote them to baselines. Requires confirm: true and explicit scenario list.
Inputs: project, environment, runId, scenarios, +3 more.
check_setup_healthC
Project setup blockers and warnings before running audits.
Inputs: project, includeEnvironments, includeIntegrations.
compare_runsC
Compare metrics between two runs.
Inputs: project, runIdA, runIdB, pillar.
create_comparison_ruleC
Add a VRT comparison rule (ignore, dynamic, layout_only) on a scenario. Requires confirm: true.
Inputs: project, scenarioLabel, selector, mode, +2 more.
explain_vrt_failureC
Structured VRT failure analysis with hypotheses and next actions.
Inputs: project, environment, scenarioLabel, viewport.
get_diff_statsC
Detailed diff stats for one scenario from the latest VRT run.
Inputs: project, environment, scenarioLabel, viewport.
get_quality_scoreC
Composite quality score and pillar breakdown for the project.
Inputs: project.
get_run_failuresC
List failed scenarios with mismatch % from a VRT run (batch, no images).
Inputs: project, environment, runId.
get_run_historyC
Recent VRT and audit runs for the project.
Inputs: project, environment, limit.
get_run_statusB
Get status and summary for a run.
Inputs: runId.
get_scenario_detailsC
Full configuration for one VRT scenario.
Inputs: project, scenarioLabel.
list_projectsA
List projects accessible with the current credentials.
Inputs: no named parameters.
list_scenariosC
List VRT scenarios (labels, URLs, viewports) for the project.
Inputs: project, environment.
perf_get_latest_reportD
Latest performance audit report.
Inputs: project.
post_pr_commentB
Post or update a VisualQ VRT summary comment on a GitHub PR (requires GitHub integration).
Inputs: project, prNumber, runId, environment, +2 more.
run_baselineC
Capture new VRT baselines.
Inputs: project, environment, scenarios, browsers.
run_frt_featureC
Run an FRT feature test suite. Requires confirm: true.
Inputs: project, environment, featureId, scenarioFilter, +2 more.
run_vrtC
Run a VRT comparison against baselines.
Inputs: project, environment, scenarios, browsers.
seo_get_reportD
Latest SEO audit report.
Inputs: project.
tracking_get_planD
Analytics tracking plan for the project.
Inputs: project.
wait_for_runC
Poll until a run completes or times out.
Inputs: runId, maxWaitMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools target distinct resources and actions: scenario listing/detail, run execution, failure/diff extraction, audit reports, approval, rules, and PR posting. A few pairs could be confused, such as wait_for_run vs get_run_status and run_baseline vs approve_vrt_results, but descriptions and return shapes generally separate them. Overall, the boundaries are clear enough for an agent to select correctly in most cases.
The dominant pattern is verb_noun, e.g., list_projects, run_vrt, get_run_history, approve_vrt_results, and post_pr_comment. The audit/tracking tools break this slightly with prefix_get style like perf_get_latest_report and tracking_get_plan, and wait_for_run uses a phrasal verb. These are minor deviations rather than a chaotic mix.
22 tools is on the heavy side, especially with some functional overlap such as wait_for_run wrapping get_run_status polling and get_run_failures vs get_diff_stats both reporting VRT diff details. The broad scope across VRT, FRT, audits, tracking, setup, and PR integration explains the count, but trimming convenience/overlapping tools would make the surface feel tighter. It is borderline, not grossly excessive.
The VRT lifecycle is well covered: scenarios, run, status, failures, diffs, analysis, approval, baseline capture, comparison rules, and PR comments. Gaps include no scenario create/update/delete, no run trigger for perf/SEO/a11y audits despite check_setup_health mentioning audits, and no cancel-run or historical audit report retrieval. These are workaroundable if configuration and audit scheduling are managed externally, but they are real gaps.
Maintenance
Related MCP Connectors
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
Visual regression testing over MCP: upload screenshots, review diffs, approve. No CI needed.
Compare Figma designs against live websites and get visual + content QA reports, from inside Claude.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that gives Claude and other clients vision capabilities including screenshot-to-code, OCR, error diagnosis, diagram analysis, data-viz insights, UI diff checks, and video analysis via any OpenAI-compatible vision endpoint.Apache 2.0

@capsulate/mcpofficial
AlicenseNot gradedqualityBmaintenanceEnables MCP clients such as Claude Desktop and Cursor to launch and control Capsulate virtual machines, providing exec, file, screenshot, accessibility-tree, checkpoint, and replay capabilities.3 npmMIT- AlicenseNot gradedqualityAmaintenanceEnables Claude Code to control a real browser through MCP tools for navigation, clicking, typing, screenshots, accessibility snapshots, and automated test scenarios. It also supports visual regression, session recording, and network/console monitoring to verify web apps directly from the terminal.106 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables Claude Code to control a real browser via MCP for navigation, clicking, screenshots, accessibility snapshots, and automated testing against web apps. It supports multi-step scenarios, assertions, network/console monitoring, session recording, and visual regression checks.106 npmMIT