# shaft-mcp

> shaft-mcp is an open-source MCP server for developer tools. Capture browser flows into reviewable Java tests and diagnose failures from evidence. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://shafthq.github.io
- **Repository:** https://github.com/shafthq/shaft_engine
- **MCP Registry name:** io.github.ShaftHQ/shaft-mcp
- **Categories:** developer tools, browser automation
- **Listing updated:** 2026-11-14

## About

SHAFT is an MIT-licensed Java test automation engine for web, mobile, API, CLI, database and desktop, and this server exposes its capture and diagnosis workflow to an agent. It is distributed as an OCI container image and runs over stdio.

The capture lifecycle records an approved browser flow, then generates native Java that you review, keeping replay evidence with the recording. On the diagnosis side, tools classify a failed Allure report or a trace to a cause such as a locator problem and offer remediation guidance. The docs stress that model choice stays with your client, tests remain ordinary Java, and proposals do not silently edit, approve or merge anything.

The engine underneath manages Selenium and Appium drivers, waits and evidence, and every run produces an Allure report; it scales through Grid, BrowserStack or LambdaTest and works with TestNG, JUnit or Cucumber. A CLI, IntelliJ plugin and agent skill pack come from the same project.

## Features

- **Flow capture:** Start, stop and generate replay from an approved browser session.
- **Generated Java:** Captured flows become native Java for review.
- **Failure diagnosis:** Classify failed Allure or trace evidence offline.
- **Review-only fixes:** Remediation guidance is a proposal and never merges itself.
- **Six test surfaces:** Engine covers web, mobile, API, CLI, database and desktop.
- **Allure on every run:** Steps, screenshots and logs land in a report.

## Good for

- Turn a manual browser walkthrough into a Java test
- Find out whether a red build is a locator issue
- Add evidence-backed triage to a CI failure
- Move an existing Selenium suite onto SHAFT

## Install

### Claude Code (Terminal)

```sh
claude mcp add shaft-mcp -- docker run -i --rm ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "shaft-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "shaft-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "shaft-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "shaft-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "shaft-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112"
      ]
    }
  }
}
```

## Tools

- `capture_start`: Begins capturing an approved browser flow.
- `capture_stop`: Stops the capture.
- `capture_generate_replay`: Generates replay evidence and Java for the captured flow.
- `doctor_analyze_failed_allure`: Classifies failed Allure evidence and suggests review-only remediation.
- `doctor_analyze_trace`: Classifies a trace to find the cause of a failure.

## FAQ

### What language are the tests?

Ordinary Java, using the SHAFT engine.

### Is it open source?

The engine is MIT licensed and on Maven Central, per its README.

### Will it change my code on its own?

No. The docs say proposals do not silently edit, approve or merge.

### How is it packaged?

As an OCI image, ghcr.io/shafthq/shaft-engine-mcp, over stdio.

### Is shaft-mcp free?

Yes. shaft-mcp is open source, so you can use and self-host it for free.

### How do I add shaft-mcp to Claude Code?

Run this command in your terminal: claude mcp add shaft-mcp -- docker run -i --rm ghcr.io/shafthq/shaft-engine-mcp:10.4.20261112

### What are the best alternatives to shaft-mcp?

The closest alternatives to shaft-mcp are REA, Browser Use, Scrapling MCP Server, Codebase Memory and GitHub.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Browser Use](https://ai-powered.com/mcp/browser-use): Browser Use is a freemium MCP server for browser automation.
- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/shaft-mcp
