# GhostQA

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/SyncTek-LLC/ghostqa  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ghostqa

## Description
AI personas navigate your web app in real browsers, find bugs and UX issues. No scripts needed.

## Tools
Capabilities this server exposes over MCP:

- **specterqa_run** — Execute behavioral tests. Parameters: `product` (str), `level` (str, optional), `directory` (str, optional). Returns a `RunReport` JSON object.
- **specterqa_list_products** — List all products and their configured journeys. No parameters required.
- **specterqa_get_results** — Retrieve a previous run report by `run_id`.
- **specterqa_init** — Initialize a new SpecterQA project at a given `directory`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "ghostqa": {
    "command": "uvx",
    "args": ["specterqa"],
    "env": {
      "ANTHROPIC_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `ANTHROPIC_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What GhostQA MCP server does

GhostQA MCP server connects an MCP-compatible agent to SpecterQA, a testing engine for evaluating applications through simulated user behavior. Instead of relying on DOM selectors or fixed interaction scripts, it uses AI personas that interpret the visible interface and attempt configured journeys. The resulting run report can include findings, screenshots, cost information, and structured test results.

The primary use case is behavioral and UX testing for web applications. A product configuration identifies the application and its services, while persona and journey YAML files describe who is testing, what they want to accomplish, and any preconditions or checkpoints. This lets teams test flows such as onboarding, registration, and dashboard access using human-readable configuration.

## How it works

A test run follows a screenshot-driven loop. Playwright captures the current page, a vision model evaluates the image along with the persona and journey context, and the selected action is executed in the browser. Actions can include clicking, filling fields, navigating, scrolling, waiting, completing a goal, or reporting that progress is blocked. The process continues until the journey succeeds, the agent becomes stuck, or a configured budget is reached.

Simple navigation can be routed to a lower-cost Haiku model, while more involved decisions use Sonnet. The project also documents optional Ollama routing for straightforward actions. Stuck detection can escalate the model and stop repeated ineffective actions. Runs can operate headlessly and return exit codes suitable for CI workflows.

## Setup and configuration

Install the Python package with Python 3.10 or newer, then download the Playwright browser binaries. MCP support is installed through the package's optional MCP extra. Running tests requires the `ANTHROPIC_API_KEY` environment variable. The optional native extra is available for macOS native applications and iOS Simulator support.

Use the initialization tool to scaffold a project directory. SpecterQA stores configuration under `.specterqa/`, with YAML files for products, personas, and journeys. Product files can define base URLs, service health checks, viewports, and cost limits. Persona files describe user characteristics and credentials, while journeys contain goals, preconditions, checkpoints, and persona references.

## Tools and capabilities

GhostQA MCP server provides these MCP operations:

- `specterqa_init` creates a new SpecterQA project at a specified directory.
- `specterqa_list_products` lists configured products and their journeys.
- `specterqa_run` executes a behavioral test for a selected product. It accepts a product name and optional level and directory values, then returns a `RunReport` JSON object.
- `specterqa_get_results` retrieves a previous report using its run ID.

The underlying project supports JSON output, JUnit XML output for CI systems, evidence directories, budget limits, template variables from persona configuration, and service precondition checks.

## Limitations and notes

The testing engine depends on Playwright browser binaries and an Anthropic API key for its documented vision-model workflow. Model calls can incur cost, although per-run, daily, and monthly limits are supported. The quality of a run depends on the product, persona, journey, and service configuration supplied in `.specterqa/`.

GhostQA is intended for configured journeys rather than unrestricted application exploration. It reports when an agent is stuck or a budget is exhausted, but those conditions should be reviewed alongside the saved screenshots and findings. The README names Claude Desktop and Cursor as MCP integration targets; no other client-specific setup is described.

_Full upstream README: https://allmcps.com/mcp/ghostqa/readme_