Skip to content
MCP server

bad-ass-mcp

Desktop GUI automation through accessibility trees, with replayable tests

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
macOS, Windows, Linux
Runs
Locally
Version
2.2.0
Listing updated
3 days ago

About bad-ass-mcp

bad-ass-mcp is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

claude mcp add bad-ass-mcp -- uvx bad-ass-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "bad-ass-mcp": {
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "bad-ass-mcp": {
      "command": "uvx",
      "args": [
        "bad-ass-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Tools this server provides (16)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Open source

Free and open source

Prices change. Check bam.holdmybeer.gg before you buy.

bad-ass-mcp 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 to bad-ass-mcp

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Browser Use

    MCP server

    Browser agents and cloud browsers for AI, with an MCP server for web tasks

    • 7 tools
    • Remote
    • Freemium
    • 121K GitHub stars
    • Browser automation
  3. MCP server for AI clients to scrape sites with HTTP and stealth browser sessions

    Runs locally
    • 17 tools
    • Open source
    • 104K GitHub stars
    • Web search and scraping
  4. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  5. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  6. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools