# ๐งช Official MCP Server for Debugg AI
**AI-driven browser automation and E2E test server** implementing the [Model Context Protocol (MCP)](https://modelcontext.org), designed to help AI agents test UI changes, simulate user behavior, and analyze visual outputs of running web applications โ all via natural language and CLI tools.
End to end testing used to be a nightmare. Not just to setup, but to manage over time as you made changes to your app.
Debugg AI's MCP server offers a NEW way to test, where you never have to worry about setting up `playwright`, local browsers or proxies with it fully remote, managed browsers that simply connect to a server running locally or remotely via a secure `tunnel`.
That means no distracting chrome pop ups as it's running tests, no managing chrome or playwright versions, and best of all - ZERO CONFIGURATION. Just grab an API key and add us to your MCP server list.
Should you want to later rerun those tests or create a suite of them to run in your CI / CD pipeline, you can see all historical test results in your dashboard - [Debugg.AI App](https://app.debugg.ai)
---
## ๐ Features
* ๐ง **MCP Protocol Support**
Full MCP server implementation with CLI and tool registry support.
* ๐งช **End-to-End Test Automation**
Trigger UI tests based on user stories or natural language descriptions via the `debugg_ai_test_page_changes` tool.
* ๐ **Localhost Web App Integration**
Test your running dev app on any `localhost` port with simulated user flows.
* ๐งพ **MCP Tool Notifications**
Sends real-time progress updates back to clients with step descriptions and UI state goals.
* ๐งท **Screenshot Support**
Capture final visual state of the page for LLMs with image rendering support.
* ๐งฑ **Stdio Server Compatible**
Plug into any MCP-compatible client (like Claude Desktop, LangChain agents, etc.) via stdin/stdout.
---
## Examples
### Input prompt: "Test the ability to create an account and login"
### Results:
**Task Completed**
- Duration: 86.80 seconds
- Final Result: Successfully completed the task of signing up and logging into the account with the email 'alice.wonderland1234@example.com'.
- Status: Success
### Full Demo:
> Watch a more in-depth, [Full Use Case Demo](https://debugg.ai/demo)
---
## ๐ ๏ธ Quickstart
### Ensure you have created a free account and generated an API Key - [DebuggAI](https://debugg.ai)
### Option 1: NPX (Local Development)
```bash
npx -y @debugg-ai/debugg-ai-mcp
```
Use this when testing or integrating into tools like Claude Desktop or your own AI agent.
### Option 2: Docker
```bash
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
```
---
## ๐งฐ MCP Tool: `debugg_ai_test_page_changes`
### Description
Run an end-to-end test on a running web app, testing a UI feature or flow described in natural language. Allows AI agents in ANY code gen platform to quickly evaluate proposed changes and
ensure new functionality works as expected.
### 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 Claude Desktop Config
```jsonc
{
"mcpServers": {
"debugg-ai-mcp": {
"command": "npx",
"args": ["-y", "@debugg-ai/debugg-ai-mcp"],
"env": {
"DEBUGGAI_API_KEY": "YOUR_API_KEY",
"TEST_USERNAME_EMAIL": "test@example.com",
"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"
}
}
}
}
```
---
## ๐ 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 | โ |
---
## ๐งโ๐ป Local Development
```bash
# Clone the repo and install dependencies
npm install
# Copy the test config and insert your creds
cp test-config-example.json test-config.json
# Run the local node-built dist
npx @modelcontextprotocol/inspector --config test-config.json --server debugg-ai-mcp-node
# OR Run the MCP server locally from above toplevel dir.
npx @modelcontextprotocol/inspector --config debugg-ai-mcp/test-config.json --server debugg-ai-mcp
```
---
## ๐ Repo Structure
```
.
โโโ e2e-agents/ # E2E browser test runners
โโโ services/ # Client for DebuggAI API
โโโ tunnels / # Secure connections to remote web browsers
โโโ index.ts # Main MCP server entry
โโโ Dockerfile # Docker build config
โโโ README.md
```
---
## ๐งฑ Built With
* [Model Context Protocol SDK](https://github.com/modelcontextprotocol)
---
## ๐ฌ Feedback & Issues
For bugs, ideas, or integration help, open an issue or contact the DebuggAI team directly.
---
## ๐ License
MIT License ยฉ 2025 DebuggAI
---
Made with ๐ฉธ, ๐ฆ, and ๐ญ in San Francisco