Skip to main content
Glama
VisualQ MCP Server

VisualQ MCP Server

by abecms

@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.

  1. Sign in to https://visualq.ai

  2. Go to Settings → Agent API Keys (org admin)

  3. Create a key with scope mcp_full

  4. Optionally set a default project slug if you mostly work on one client

  5. Copy the Cursor MCP config snippet

  6. 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-site

Or 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

VISUALQ_API_KEY

yes

—

Org agent key vq_org_live_… or legacy project key vq_live_…

VISUALQ_BASE_URL

no

https://visualq.ai

VisualQ instance (use your origin for self-hosted)

VISUALQ_DEFAULT_PROJECT

no

—

Default project slug injected into tool args

VISUALQ_TOOL_PROFILE

no

qa

qa (recommended), full, or legacy aliases vrt-qa / frt-qa / tracking-qa → qa

VISUALQ_MCP_HTTP

no

—

Set 1 to run local Streamable HTTP on 127.0.0.1:3847

VISUALQ_MCP_PORT

no

3847

HTTP mode port

API key scopes

Scope

MCP read

MCP write (confirm: true)

CI /api/ci/*

mcp_read

yes

no

no

mcp_full

yes

yes

no

ci (project key)

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.js

Sync tool manifest from the visualq backend (sibling repo):

cd ../visualq && npm run mcp:export-manifest
cd ../visualq-mcp && npm run sync-manifest

Before 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 public

Repository

Available Tools

22 tools
a11y_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

    C2.5/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT