# bad-ass-mcp

> bad-ass-mcp is an open-source MCP server for developer tools. Desktop GUI automation through accessibility trees, with replayable tests. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, Windows, Linux, CLI
- **Website:** https://bam.holdmybeer.gg
- **Repository:** https://github.com/holdmybeer-gg/bad-ass-mcp
- **MCP Registry name:** io.github.HoldMyBeer-gg/bad-ass-mcp
- **Categories:** developer tools, browser automation
- **Listing updated:** 2026-11-14

## About

Instead of guessing from pixels, this server reads the accessibility tree that each desktop app exposes for screen readers: AXUIElement on macOS, UI Automation on Windows and AT-SPI2 on Linux. It clicks Save because it knows which element is the Save button, so a new theme, font or window size does not break the test.

The workflow it pitches is explore once, replay forever. An AI such as Claude, Codex, Gemini or a local model clicks through the app one time, the path is written down as a readable JSON script, and the bad-ass-mcp run command replays it later with no AI and no cost. Reports list each step, put failures first and include a screenshot after each part. A check command catches script typos before anything runs.

For games and 3D views that expose no tree, it falls back to screenshots and coordinate clicks. It installs with pip and is free and open source.

## Features

- **Accessibility tree control:** Finds buttons, menus and text boxes by role and name on macOS, Windows and Linux.
- **Replayable test scripts:** Turns an exploratory session into a readable JSON test that runs without AI.
- **Pass and fail reports:** Produces an HTML report with a screenshot after each phase.
- **Vision fallback:** Uses screenshots, click_at and drag where an app exposes no tree.
- **Recording:** Captures the screen as a GIF or MP4 while automation runs.
- **Script validation:** The check command flags unknown keys and suggests corrections.

## Good for

- Smoke-test a desktop app before each release
- Drive native apps from an assistant without screenshot loops
- Check that an app is usable with a screen reader
- Record a demo clip of an automated session

## Install

### Claude Code (Terminal)

```sh
claude mcp add bad-ass-mcp -- uvx bad-ass-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "bad-ass-mcp": {
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "bad-ass-mcp": {
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "bad-ass-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "bad-ass-mcp": {
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "bad-ass-mcp": {
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
```

## Tools

- `list_windows`: List all visible application windows.
- `get_tree`: Full accessibility tree for a window as nested JSON.
- `find_elements`: Find elements by role and/or name.
- `click`: Click or invoke an element, foreground-independent.
- `click_at`: Click at absolute screen coordinates for webview or canvas UI.
- `drag`: Drag and drop with real pointer events.
- `type_text`: Type text into a field.
- `select_option`: Select an option in a combo box or list.
- `get_value`: Get the current value or text of an element.
- `wait_for_window`: Wait until a window matching a pattern appears.
- `wait_for_element`: Wait until an element exists and optionally has a given state.
- `screenshot`: Capture a PNG.
- `start_recording`: Start recording the screen or a window.
- `stop_recording`: Stop recording and export as GIF or MP4.
- `learn_layout`: Resolve semantic names to live handle IDs.
- `run_sequence`: Execute a list of actions server-side.

## FAQ

### Which platforms does it support?

macOS, Windows, Linux and the Steam Deck.

### Does every test need an AI?

No. The AI is used once to explore the app, then BAM replays the saved script without AI.

### How do I install it?

pip install bad-ass-mcp.

### What about apps that do not expose accessibility data?

Games and 3D views fall back to looking at the screen.

### Is bad-ass-mcp free?

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

### How do I add bad-ass-mcp to Claude Code?

Run this command in your terminal: claude mcp add bad-ass-mcp -- uvx bad-ass-mcp

### What are the best alternatives to bad-ass-mcp?

The closest alternatives to bad-ass-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/bad-ass-mcp
