aiTest MCP Server

AI-native browser testing, directly from your coding agent.

aiTest MCP Server connects AI coding tools (Cursor, Claude Desktop, Copilot) to the aiTest cloud testing platform. Describe what you want to test in plain English, and the AI engine handles the rest — planning, browser execution, root-cause analysis, and UX insights.

Quick Start

npx @aitest/mcp

Prerequisites

• Node.js >= 18
• An aiTest API key (get one here) or run against a local dev server
• One of: Cursor, Claude Desktop, or any MCP-compatible client

Configuration

Set these environment variables (or use your MCP client's config):

Variable	Required	Default	Description
AITEST_API_KEY	✅	—	Your aiTest API key (aitest_sk_...)
AITEST_API_URL	—	http://localhost:8000/api/v1	aiTest REST API base URL

Cursor Setup

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "aitest": {
      "command": "npx",
      "args": ["@aitest/mcp"],
      "env": {
        "AITEST_API_KEY": "aitest_sk_your_key_here"
      }
    }
  }
}

Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "aitest": {
      "command": "npx",
      "args": ["@aitest/mcp"],
      "env": {
        "AITEST_API_KEY": "aitest_sk_your_key_here"
      }
    }
  }
}

Tools

aitest_run

Submit a new browser test job.

Parameters:
  url          — Target URL to test
  description  — What to test (natural language)
  credentials? — Login credentials { email, password }
  options?     — Test config { max_retries, screenshot_mode, timeout_seconds }

Returns: job_id + estimated completion time

Example: "Test that the login page accepts valid credentials, rejects invalid ones, and shows appropriate error messages."

aitest_status

Check the current status of a test job.

Parameters:
  job_id — The job ID from aitest_run

Returns: status (created/queued/executing/completed/failed) + timing

aitest_report

Get the full test report (only available when job is completed).

Parameters:
  job_id — The job ID from aitest_run

Returns: Summary, step-by-step results, root-cause analysis, UX insights

Development

# Clone
git clone git@github.com:rongxianzhuo/aitest-mcp.git
cd aitest-mcp

# Install
npm install

# Build
npm run build

# Run locally (against local aiTest API)
AITEST_API_URL=http://localhost:8000/api/v1 \
AITEST_API_KEY=aitest_sk_test \
  node dist/index.js

Architecture

AI Coding Agent (Cursor / Claude)
        │
        │  MCP Protocol (stdio)
        ▼
  aitest-mcp (thin proxy)
        │
        │  REST HTTPS
        ▼
  aiTest Cloud Platform
        │
        ├── FastAPI Server (Railway)
        ├── AI Engine (test planning + agent loop + analysis)
        ├── Supabase (auth + db + storage)
        └── Browser Sandbox (Playwright / Browserbase)

The MCP server is intentionally thin — zero AI logic, zero browser automation. It translates MCP tool calls into REST API requests and formats the responses for LLM consumption.

License

MIT — see LICENSE