@specwright/mcp

@specwright/mcp

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

What's Inside

Capability	Tools	Powered by
E2E pipeline	9 tools (e2e_*)	Built-in
File management	4 tools (read_file, write_file, edit_file, list_directory)	Built-in
Browser automation	21 tools (browser_*)	@playwright/mcp (configured separately)
File conversion	convert_to_markdown	markitdown-mcp-npx (bundled)

Pipeline Tools

Tools appear in Claude Desktop as E2E Setup, E2E Automate, etc. (proper capitalisation via MCP annotations.title).

Tool	Display Name	Description
e2e_setup	E2E Setup	Native form UI to collect pipeline config (module name, page URL, test input, options). Falls back to guided chat questions when native forms are unavailable.
e2e_automate	E2E Automate	Read instructions.js and return full 10-phase pipeline execution plan with □/🔄/✅ progress tracking
e2e_configure	E2E Configure	Init setup, read/list/add entries in instructions.js
e2e_explore	E2E Explore	Browser exploration with auth, scenario-driven interactions, seed file, plan file, and memory update
e2e_plan	E2E Plan	Generate seed.spec.js + test plan from discovered selectors
e2e_generate	E2E Generate	Generate BDD .feature files and step definitions from a test plan
e2e_execute	E2E Execute	Run Playwright tests (seed or BDD mode)
e2e_heal	E2E Heal	Auto-heal failing BDD tests (up to 3 iterations) with dual memory update
e2e_status	E2E Status	Check pipeline state — config, seed file, plans, generated tests, results

File Management Tools

Claude Desktop has no native Read/Write tools — these four built-in tools give the pipeline native file access scoped to the configured project root.

Tool	Description
read_file	Read any file under the project root
write_file	Write or overwrite a file (creates parent directories)
edit_file	Exact-string replace within a file (fails if string not found or ambiguous)
list_directory	List files and subdirectories at a path

All paths are validated — traversal outside the project root is blocked.

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 and Specwright Desktop:

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

Claude Desktop Setup

Claude Desktop requires a separate claude_desktop_config.json entry. The pipeline needs two MCP servers: specwright (pipeline + file tools) and playwright-test (browser automation).

1. Add to ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "specwright": {
      "command": "npx",
      "args": ["@specwright/mcp"],
      "env": {
        "SPECWRIGHT_PROJECT": "/absolute/path/to/your/project"
      }
    },
    "playwright-test": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--output-dir",
        "/tmp/playwright-mcp"
      ]
    }
  }
}

Using nvm, asdf, or volta? Claude Desktop launches MCP servers via macOS launchd, which uses a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) — not your shell's PATH. If npx is installed via a version manager it won't be found. Fix it by using the absolute path to npx and adding a PATH env override:

{
  "mcpServers": {
    "specwright": {
      "command": "/Users/you/.nvm/versions/node/v22.12.0/bin/npx",
      "args": ["@specwright/mcp"],
      "env": {
        "SPECWRIGHT_PROJECT": "/absolute/path/to/your/project",
        "PATH": "/Users/you/.nvm/versions/node/v22.12.0/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    },
    "playwright-test": {
      "command": "/Users/you/.nvm/versions/node/v22.12.0/bin/npx",
      "args": ["@playwright/mcp@latest", "--output-dir", "/tmp/playwright-mcp"],
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.12.0/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

Find your npx path with: which npx
Find your Node version path with: ls ~/.nvm/versions/node/ (or ~/.asdf/shims/npx for asdf)

2. Restart Claude Desktop

Why the key name must be playwright-test

The Specwright pipeline calls browser tools using the exact prefix mcp__playwright-test__* (e.g. mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_snapshot). This prefix is derived directly from the MCP server key name — if your entry is named anything else (e.g. "playwright", "pw", "browser"), the pipeline tools will not resolve and exploration will fail.

Already have Playwright installed under a different name? Rename it:

// ❌ Before — wrong key name
"playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }

// ✅ After — correct key name + required --output-dir
"playwright-test": {
  "command": "npx",
  "args": ["@playwright/mcp@latest", "--output-dir", "/tmp/playwright-mcp"]
}

Why --output-dir is required

Claude Desktop starts the Playwright MCP from the system root (/), so a relative path like .playwright-mcp resolves to /.playwright-mcp and fails with ENOENT. The --output-dir flag pins screenshots and traces to an absolute path. /tmp/playwright-mcp works universally across all projects without any project-specific configuration.

3. Set project path

Either set SPECWRIGHT_PROJECT in claude_desktop_config.json (as shown above), or run e2e_configure after Claude Desktop connects — it stores the path in ~/.specwright/config.json.

Note: Environment variable substitution (${PWD}) is not supported in Claude Desktop — use explicit absolute paths.

Jira / Atlassian (Required for Jira URL inputs)

If any instructions.js entry has inputs.jira.url set, the Atlassian MCP must be present — otherwise mcp__atlassian__getJiraIssue won't exist and Phase 3 will fail when it tries to fetch the ticket.

Add Atlassian as a third entry — Claude handles OAuth natively, no API token needed:

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

On first use, Claude will prompt you to authorise access to your Atlassian account in the browser. No credentials are stored in the config.

No Jira? Leave inputs.jira.url empty in instructions.js and use the instructions[] array to describe scenarios directly — the Atlassian MCP is not needed.

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_configure 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 which handles generation and healing directly — no key needed.

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.

Pipeline Behaviour

Progress tracking

e2e_automate emits an 8-phase □/🔄/✅ todo list after each phase so you can see pipeline progress in Claude Desktop where tool results are hidden:

✅ Phase 1: Pipeline loaded
✅ Phase 2: Input source detected
✅ Phase 3: Plan file written
🔄 Phase 4: Browser exploration — in progress
□ Phase 5–8: pending

Run commands

The pipeline generates playwright-bdd tests — the correct run command depends on the module category:

# @Modules
npx bddgen && npx playwright test --project setup --project main-e2e --grep "@modulename"

# @Workflows
npx bddgen && npx playwright test --project setup --project precondition --project workflow-consumers --grep "@modulename"

npx bddgen MUST run first — it compiles .feature → .features-gen/*.spec.js. Never use npx cucumber-js.

Browser exploration

e2e_explore performs scenario-driven live browser interactions — one browser action per instruction, not just a single page snapshot. Agent memory is used as a selector hint but never replaces live verification.

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.

Changelog

See CHANGELOG.md for the full version history.

Part of Specwright

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