Skip to main content
Glama
MCP QA Server

MCP QA Server

by 404Yeti

MCP QA Server

A reusable Model Context Protocol (MCP) server for QA automation testing. Works across multiple project types — web apps, API services, CLI tools, VM environments, and WordPress sites.

The server itself is project-agnostic. All project-specific test targets live in a .mcp-qa-config.json file inside each project's repository.

Quick Start

# Clone and install
git clone <repo-url> mcp-qa-server
cd mcp-qa-server
npm install
npm run build

# Install CLI globally
npm link

# In any project directory:
mcp-qa init

Related MCP server: web-automation-mcp

Adding to Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "qa": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-qa-server/dist/src/index.js"]
    }
  }
}

Then ask Claude: "Run QA tests for this project" — Claude will use the qa_run_tests tool with your project path.

CLI Commands

mcp-qa init

Interactive initialization. Creates .mcp-qa-config.json in the current directory with sensible defaults based on your project type.

$ mcp-qa init

  MCP QA Server — Project Initialization
  ──────────────────────────────────────────

? Project name: my-web-app
? Project type: Web Application
? Base URL: http://localhost:3000
? Which testing modules do you need? Web/UI Testing, API Testing
? Report format: Console

mcp-qa validate

Validates the config file in the current directory. Reports specific errors with field paths.

$ mcp-qa validate

  Config is valid
    Project:  my-web-app
    Type:     web-app
    Modules:  web, api (2 active)
    Issues:   none

mcp-qa list-modules

Lists all available testing modules.

$ mcp-qa list-modules

  Available Modules:
    web            Web/UI testing (page loads, forms, workflows)
    api            API endpoint testing (REST, response validation)
    cli            CLI tool testing (command execution, output validation)
    vm             VM environment validation (tools, deps, configs)
    wordpress      WordPress testing (plugins, themes, pages)
    integration    Integration testing (cross-module orchestration)
    performance    Performance testing (load, response times)

MCP Tools

The server exposes 5 tools to Claude:

Tool

Description

qa_run_tests

Run all (or filtered) tests for a project

qa_run_module

Run a single testing module

qa_list_modules

List available modules and their status

qa_check_config

Validate the project config file

qa_get_report

Retrieve the last test report

Testing Modules

Web/UI (web)

Browser-based testing via Playwright (headless Chromium).

  • Page loads — URL reachability, status codes, load timing, content checks

  • Forms — Field filling, submission, redirect/content/error validation

  • Workflows — Multi-step browser interactions (navigate, click, fill, wait, assert)

Requires: npx playwright install chromium

API (api)

HTTP endpoint testing.

  • REST requests — All HTTP methods, headers, query params, request bodies

  • Response validation — Status codes, body type, key presence, value matching

  • Authentication — Bearer token, API key, Basic auth via environment variables

  • Chaining — Capture response values for use in subsequent requests

CLI (cli)

Command-line tool testing.

  • Execution — Spawn processes with args, env vars, stdin, timeout

  • Output validation — stdout/stderr exact match, contains, regex patterns

  • Exit codes — Assert specific exit codes

  • File creation — Verify commands create expected files with expected content

VM Environment (vm)

Validate development environment setup.

  • Tool checks — Binary existence on PATH via command -v

  • Version validation — Semver range checking (e.g., >=20.0.0)

  • Dependencies — Arbitrary command-based version checks

  • Config files — Existence, permissions, content pattern matching

  • Services — Systemd/launchd service status checks

WordPress (wordpress)

WordPress-specific testing.

  • Plugins — Installation and activation status via WP-CLI or HTTP fallback

  • Themes — Active theme validation

  • Pages — Content loading, status codes, content checks

Performance (performance)

Basic load and response time testing.

  • Timing — Single-request response time thresholds

  • Load testing — Concurrent request bursts with p50/p95/p99 percentiles

  • Error rates — Track failures under load

Integration (integration)

Cross-module test orchestration.

  • Scenarios — Sequential steps spanning multiple modules

  • Shared state — Pass data between modules via context.store

  • Stop on failure — Abort scenario when a step fails

Configuration

Config files live in each project as .mcp-qa-config.json. Run mcp-qa init to generate one, or create manually.

Schema

{
  "configVersion": 1,
  "projectName": "my-project",
  "projectType": "web-app",        // web-app | api-service | cli-tool | vm-environment | wordpress-site
  "modules": ["web", "api"],       // Which modules to enable
  "reportFormat": "console",       // console | json | github
  "baseUrl": "http://localhost:3000",
  "timeout": 30000,                // Global timeout in ms
  "env": {},                       // Environment variables for test runs
  "moduleConfig": {                // Per-module config (see below)
    "web": { ... },
    "api": { ... }
  }
}

Module Config Examples

See the templates/ directory for complete examples:

Report Formats

Console

Human-readable with [PASS]/[FAIL]/[SKIP]/[ERR!] indicators, file:line error locations, module grouping, and summary.

JSON

Machine-readable structured output. Full TestReport object with all results, timing, and error details.

GitHub Actions

Annotation format for CI. Produces ::error file=X,line=Y::message output that creates inline annotations on pull requests.

Error Reporting

All errors include location information when available:

  • Config errors — File path + line number pointing to the invalid field

  • Test failures — Test name, module, and the config entry that defined the test

  • Runtime errors — Stack traces with source locations

Console format: .mcp-qa-config.json:25 — Expected redirect to /dashboard GitHub format: ::error file=.mcp-qa-config.json,line=25::Expected redirect to /dashboard

Development

npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm test          # Run tests
npm run lint      # Lint

Architecture

.mcp-qa-config.json (per project)
        │
        ▼
┌─── MCP QA Server ──────────────┐
│  Config Loader → Module Registry│
│       │              │          │
│  Test Runner ← Base Module      │
│       │              │          │
│  Reporter       7 Modules       │
│  (console/json/github)          │
└─────────────────────────────────┘
        │
        ▼
  Claude Desktop (via stdio)

The server reads .mcp-qa-config.json from disk on every tool call (never cached) so edits are picked up immediately.

Available Tools

5 tools
qa_check_configA

Validate a project's .mcp-qa-config.json file. Returns validation results with specific error messages and line numbers if invalid.

Inputs: projectPath (required).

qa_get_reportB

Retrieve the last test report for a project. Optionally specify a different output format than what the config defaults to.

Inputs: projectPath (required), format.

qa_list_modulesA

List available QA testing modules. If a projectPath is provided, also shows which modules are enabled for that project.

Inputs: projectPath.

qa_run_moduleA

Run a single QA test module for a project. Use this for targeted testing of a specific area (e.g. just API tests or just VM checks).

Inputs: module (required), projectPath (required), testFilter.

qa_run_testsA

Run QA tests for a project. Loads .mcp-qa-config.json from the project path, executes the configured test modules, and returns a formatted report. Optionally filter by module names or test name substring.

Inputs: projectPath (required), filter, modules.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: validating config, retrieving reports, listing modules, running specific modules, and running full test suites. There is no overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent 'qa_verb_noun' pattern (e.g., qa_check_config, qa_run_tests), making them predictable and easy to understand.

    Tool Count5/5

    Five tools is well-scoped for a QA-focused server, covering essential operations without being excessive or insufficient.

    Completeness5/5

    The tool set covers the core workflow: configuration validation, module listing, selective or full test execution, and report retrieval. No obvious gaps for the given domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      An MCP server that gives Claude Code a real browser, enabling it to navigate, click, type, screenshot, and inspect web pages during development. It also supports multi-step JSON test scenarios, assertions, session recording, and visual regression testing against web apps.
      106 npm
      MIT