@specwright/mcp

@specwright/mcp

Unified MCP server for Specwright — bundles Playwright browser automation, file conversion, and a full 10-phase E2E test generation pipeline in a single npx command.

What's Inside

Capability	Tools	Powered by
E2E pipeline	9 tools (e2e_*)	Built-in
Browser automation	21 tools (browser_*)	@playwright/mcp (bundled)
File conversion	convert_to_markdown	markitdown-mcp-npx (bundled)

No external dependencies to install — Playwright and markitdown are bundled and resolved locally.

Pipeline Tools

Tool	Description
e2e_setup	Native form UI to collect pipeline config (module name, page URL, test input, options)
e2e_automate	Read instructions.js and return full 10-phase pipeline execution plan
e2e_configure	Init setup, read/list/add entries in instructions.js
e2e_explore	Get exploration plan with auth status, known selectors, step-by-step instructions
e2e_plan	Generate seed.spec.js + test plan from discovered selectors
e2e_generate	Generate BDD .feature files and step definitions from a test plan
e2e_execute	Run Playwright tests (seed or BDD mode) via execution-manager agent
e2e_heal	Auto-heal failing BDD tests (up to 3 iterations)
e2e_status	Check pipeline state — config, seed file, plans, generated tests, results

Quick Start

Run this in your project root to scaffold everything automatically:

npx @specwright/plugin init

This generates a .mcp.json — the same config works for Claude Code CLI, Claude Desktop, and Specwright Desktop:

{
  "mcpServers": {
    "specwright": {
      "command": "npx",
      "args": ["@specwright/mcp"]
    }
  }
}

That's the minimal config. All three env vars below are optional depending on your setup.

Environment Variables

Variable	Required	Description
SPECWRIGHT_PROJECT	Optional	Absolute path to your project root. If omitted, the server reads from ~/.specwright/config.json (set automatically by e2e_setup on first run).
ANTHROPIC_API_KEY	Optional	Enables autonomous SDK mode for e2e_generate and e2e_heal. Without it, both tools return full context + instructions to the host Claude (Claude Code / Claude Desktop) which handles generation and healing directly — no key needed.

Claude Desktop: Environment variable substitution (${PWD}) is not supported — set values explicitly in claude_desktop_config.json.

Jira / Atlassian (Optional)

If your team uses Jira, add Atlassian as a separate MCP entry — Claude handles OAuth natively, no token needed:

{
  "mcpServers": {
    "specwright": { "command": "npx", "args": ["@specwright/mcp"] },
    "atlassian": {
      "type": "streamable-http",
      "url": "https://mcp.atlassian.com/v1/mcp"
    }
  }
}

File Conversion

convert_to_markdown accepts a uri parameter (file URI or URL):

file:///path/to/document.pdf
file:///path/to/spreadsheet.xlsx
file:///path/to/document.docx
https://example.com/page

Supported formats: PDF, Excel (XLSX), Word (DOCX), PowerPoint (PPTX), CSV, HTML, images, and more.

First use sets up a Python virtual environment automatically (~10–30s). Subsequent starts reuse the cached environment and are instant.

Project Setup

Initialize a new project with the Specwright plugin:

npx @specwright/plugin init

This creates .specwright.json, instructions.js, Playwright config, and all required E2E framework files.

Part of Specwright

This MCP server is part of the Specwright E2E test automation platform.