DebuggAI MCP server for AI agents

Debugg AI's MCP server implements the Model Context Protocol to provide AI-driven browser automation and end-to-end testing capabilities. It enables AI agents to test UI changes, simulate user behavior, and analyze visual outputs of web applications through natural language and CLI tools without requiring complex local setup.

Installation Options

Using NPX (Recommended for Local Development)

Run the MCP server directly using npx:

npx -y @debugg-ai/debugg-ai-mcp

This method is ideal when testing or integrating with tools like Claude Desktop or your own AI agent.

Using Docker

Run the server in a Docker container:

docker run -i --rm --init \
  -e DEBUGGAI_API_KEY=your_api_key \
  -e TEST_USERNAME_EMAIL=your_test_email \
  -e TEST_USER_PASSWORD=your_password \
  -e DEBUGGAI_LOCAL_PORT=3000 \
  -e DEBUGGAI_LOCAL_REPO_NAME=your-org/your-repo \
  -e DEBUGGAI_LOCAL_BRANCH_NAME=main \
  -e DEBUGGAI_LOCAL_REPO_PATH=/app \
  -e DEBUGGAI_LOCAL_FILE_PATH=/app/index.ts \
  quinnosha/debugg-ai-mcp

Configuration

Environment Variables

Variable	Description	Required
`DEBUGGAI_API_KEY`	API key for calling DebuggAI backend	✅
`TEST_USERNAME_EMAIL`	Email of test user account	❌
`TEST_USER_PASSWORD`	Password of test user account	❌
`DEBUGGAI_LOCAL_PORT`	Local port your app runs on	✅
`DEBUGGAI_LOCAL_REPO_NAME`	GitHub repo name	❌
`DEBUGGAI_LOCAL_BRANCH_NAME`	Branch name	❌
`DEBUGGAI_LOCAL_REPO_PATH`	Local path to repo root	❌
`DEBUGGAI_LOCAL_FILE_PATH`	File to test	❌

Claude Desktop Configuration

Add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "debugg-ai-mcp": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "YOUR_API_KEY",
        "TEST_USERNAME_EMAIL": "[email protected]",
        "TEST_USER_PASSWORD": "supersecure",
        "DEBUGGAI_LOCAL_PORT": 3000,
        "DEBUGGAI_LOCAL_REPO_NAME": "org/project",
        "DEBUGGAI_LOCAL_BRANCH_NAME": "main",
        "DEBUGGAI_LOCAL_REPO_PATH": "/Users/you/project",
        "DEBUGGAI_LOCAL_FILE_PATH": "/Users/you/project/index.ts"
      }
    }
  }
}

Using the MCP Tool

Tool: `debugg_ai_test_page_changes`

This tool runs end-to-end tests on a running web application, testing UI features or flows described in natural language.

Input Parameters

Name	Type	Required	Description
`description`	string	✅	What feature or page to test (e.g. "Signup page form")
`localPort`	number	❌	Port of your running app (default: `3000`)
`repoName`	string	❌	GitHub repo name
`branchName`	string	❌	Current branch
`repoPath`	string	❌	Absolute path to the repo
`filePath`	string	❌	File to test

Example Use Case

When you provide a natural language test description like "Test the ability to create an account and login", the MCP server:

Connects to your running web application
Executes a browser automation sequence that:
- Navigates to the signup page
- Fills out the registration form
- Submits the form
- Attempts to login with the new credentials
Returns test results including:
- Duration of the test
- Final result with success/failure status
- Screenshots of the final state (for LLMs with image rendering support)

The test results will indicate whether the operation was successful and provide detailed information about the execution.

Features

MCP Protocol Support: Full implementation with CLI and tool registry support
End-to-End Test Automation: Trigger UI tests based on natural language descriptions
Localhost Web App Integration: Test your running development app on any localhost port
Real-time Progress Updates: Provides notifications with step descriptions and UI state goals
Screenshot Support: Captures the final visual state of the page

For more detailed demos and examples, visit Debugg.AI.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "debugg-ai-mcp" '{"command":"npx","args":["-y","@debugg-ai/debugg-ai-mcp"],"env":{"DEBUGGAI_API_KEY":"YOUR_API_KEY","TEST_USERNAME_EMAIL":"[email protected]","TEST_USER_PASSWORD":"supersecure","DEBUGGAI_LOCAL_PORT":3000,"DEBUGGAI_LOCAL_REPO_NAME":"org/project","DEBUGGAI_LOCAL_BRANCH_NAME":"main","DEBUGGAI_LOCAL_REPO_PATH":"/Users/you/project","DEBUGGAI_LOCAL_FILE_PATH":"/Users/you/project/index.ts"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "debugg-ai-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@debugg-ai/debugg-ai-mcp"
            ],
            "env": {
                "DEBUGGAI_API_KEY": "YOUR_API_KEY",
                "TEST_USERNAME_EMAIL": "[email protected]",
                "TEST_USER_PASSWORD": "supersecure",
                "DEBUGGAI_LOCAL_PORT": 3000,
                "DEBUGGAI_LOCAL_REPO_NAME": "org/project",
                "DEBUGGAI_LOCAL_BRANCH_NAME": "main",
                "DEBUGGAI_LOCAL_REPO_PATH": "/Users/you/project",
                "DEBUGGAI_LOCAL_FILE_PATH": "/Users/you/project/index.ts"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "debugg-ai-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@debugg-ai/debugg-ai-mcp"
            ],
            "env": {
                "DEBUGGAI_API_KEY": "YOUR_API_KEY",
                "TEST_USERNAME_EMAIL": "[email protected]",
                "TEST_USER_PASSWORD": "supersecure",
                "DEBUGGAI_LOCAL_PORT": 3000,
                "DEBUGGAI_LOCAL_REPO_NAME": "org/project",
                "DEBUGGAI_LOCAL_BRANCH_NAME": "main",
                "DEBUGGAI_LOCAL_REPO_PATH": "/Users/you/project",
                "DEBUGGAI_LOCAL_FILE_PATH": "/Users/you/project/index.ts"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

DebuggAI MCP server