Tools

BugBug MCP provides 50 tools that let AI assistants work with BugBug projects through the Model Context Protocol.

BugBug MCP access requires a Pro or higher BugBug plan. Enable human confirmation for authorized changes and runs.

To reduce risk, enable human confirmation in your AI client for tools that create, update, delete, import, or run BugBug assets. Use read-only tools first when planning, reviewing, or debugging.

Tests

Use these tools to list, inspect, create, update, import, and run BugBug tests.

Tool	Description
bugbug_list_tests	List BugBug tests. Supports filtering by name.
bugbug_get_test	Get details of a specific test.
bugbug_create_tests	Create one or more new tests.
bugbug_patch_test	Partially update a test.
bugbug_delete_test	Delete a test by ID.
bugbug_import_test	Import a test from YAML or ZIP.
bugbug_update_step_position	Move a step within a test.
bugbug_run_test	Start a test run by test name or ID.

Sample prompt:

Inspect a login test and its final assertion

For the <project> login flow, find the matching test and inspect its steps and final assertion. This is read-only. If multiple tests match or context is missing, ask me to choose. Return the test name, the assertion assessment, and specific evidence; do not change anything.

Suites

Use these tools to list, inspect, create, update, delete, and run test suites.

Tool	Description
bugbug_list_suites	List BugBug test suites. Supports filtering by name.
bugbug_get_suite	Get details of a specific suite.
bugbug_create_suite	Create a new suite.
bugbug_update_suite	Update a suite.
bugbug_delete_suite	Delete a suite by ID.
bugbug_run_suite	Start a suite run by suite ID.

Sample prompt:

Recommend a smoke-test suite

For <project> and the <release/environment> deployment, list the smoke suites and inspect their membership and recent run results. This is read-only. If the target environment or release criteria are missing, ask me. Return the recommended suite, rationale, and evidence; do not start a run.

Test Runs & Suite Runs

Use these tools to inspect test and suite run history, wait for active runs, and stop running jobs.

Tool	Description
bugbug_list_test_runs	List historical test runs.
bugbug_get_test_run	Get detailed results of a test run.
bugbug_list_suite_runs	List suite runs.
bugbug_get_suite_run	Get detailed results of a suite run.
bugbug_watch_run_progress	Wait for a test or suite run to finish and stream progress.
bugbug_stop_run	Stop a running test or suite run.

Sample prompt:

Diagnose the latest failed checkout run

For the <project> checkout test, inspect the latest failed run and its failed-step details, screenshots, logs, and DOM evidence. This is read-only. If no failed run or test identifier is available, ask me for one. Return the failure classification, supporting evidence, and smallest proposed fix; do not modify or rerun the test.

Steps

Use these tools to inspect, create, update, and delete test steps.

Tool	Description
bugbug_get_step	Get details of a specific step.
bugbug_create_steps	Create one or more steps with typed step payloads.
bugbug_update_steps	Partially update one or more steps.
bugbug_delete_steps	Delete steps by ID.

Sample prompt:

Propose a reliable final assertion

For test <test-id> in <project>, inspect the existing final steps and propose an assertion payload for <expected outcome>. Do not mutate anything until I approve the exact payload. If the outcome, selector, or test target is unclear, ask me. Return the proposed payload and why it is reliable.

Groups and components

Use these tools to work with step groups and reusable components.

Tool	Description
bugbug_list_groups	List groups and components.
bugbug_get_group	Get details of a group or component.
bugbug_create_groups	Create one or more groups or reusable components.
bugbug_update_group	Partially update a group or component.
bugbug_convert_group_to_component	Convert a regular group into a reusable component.
bugbug_convert_component_to_group	Convert a reusable component back to a regular group.
bugbug_insert_group_in_test	Insert a group into a test.
bugbug_delete_group	Delete a group by ID.
bugbug_list_components	List reusable components.
bugbug_get_component_usage	Show where a component is used.
bugbug_insert_component_into_test	Link a reusable component into a test.
bugbug_unlink_component_from_test	Remove a linked component from a test.

Sample prompt:

Find reusable component opportunities

In <project>, inspect the named tests or suites for repeated login steps and component usage. This is read-only. If the scope is not specified, ask me which tests to inspect. Return affected tests, the evidence for duplication, and a recommended component boundary; do not refactor.

Debugging

Use these tools when diagnosing failed runs, broken selectors, or DOM-related problems.

Tool	Description
bugbug_query_dom_snapshot_element	Query a DOM snapshot by CSS selector or XPath.
bugbug_get_failed_step_run_details	Get details of a failed step run.

Sample prompt:

Diagnose a failed step with run evidence

For <project>, diagnose failed run <run-id>, focusing on failed step <step-run-id> when provided. This is read-only: inspect failed-step details, screenshots, logs, and DOM evidence before reaching a conclusion. If the run or step ID is missing, ask me for it. Return the failure category, evidence, and smallest proposed fix; do not update the test.

Visual regression

Use these tools to inspect visual regression reference screenshots and resolve visual review results.

Tool	Description
bugbug_list_visual_regression_reference_screenshots	List reference screenshots for a step.
bugbug_resolve_visual_regression_review	Accept or reject a visual regression difference.
bugbug_delete_visual_regression_reference_screenshot	Delete a visual regression reference screenshot.

Sample prompt:

Review a visual regression difference

For <project>, review visual regression failure <run-id>/<step-run-id>. Inspect the expected, observed, and diff screenshots and relevant failed-step details. Do not accept or update a baseline unless I explicitly approve it. If the target run is missing, ask me. Return the observed difference, risk assessment, and recommendation with evidence.

Profiles and variables

Use these tools to inspect run profiles and manage variables used by tests.

Tool	Description
bugbug_list_profiles	List BugBug run profiles.
bugbug_get_profile	Get details of a specific run profile.
bugbug_get_variables_list	List BugBug variables.
bugbug_create_new_variable	Create a new BugBug variable.
bugbug_update_variable	Partially update a custom BugBug variable by key.

Sample prompt:

Inspect checkout profiles and variables

For <project>, inspect the profiles and variables available for checkout testing against <environment>. This is read-only. If the environment or checkout test is ambiguous, ask me. Return the matching profile, required variable keys, and any missing configuration; do not create or update variables.

Project and docs

Use these tools to select project context and answer BugBug documentation questions.

Tool	Description
bugbug_list_projects	List projects accessible to the authenticated user or token.
bugbug_get_project_settings	Get settings for the active project.
bugbug_upload_project_artifact	Upload a file for use in an upload-file test step.
bugbug_ask_docs	Answer a question from BugBug documentation with source links.

Sample prompt:

Inspect project settings for cloud execution

For <project>, identify the connected BugBug project and inspect settings that may affect cloud execution in <environment>. This is read-only. If more than one project is available or the environment is unspecified, ask me to choose. Return the selected project, relevant settings, and their likely impact with evidence; do not change settings.

Related docs

• BugBug MCP

• BugBug Plugin

• BugBug Skills

FAQ

What can the BugBug MCP tools do?

BugBug MCP provides tools for working with projects, tests, suites, steps, components, profiles, variables and test runs. AI agents can inspect existing assets, create and update tests, start runs, monitor results, diagnose failures, review visual regression differences and import test definitions when authorized.

Which BugBug MCP tools are read-only, and which can change project data?

Tools beginning with actions such as list, get and query are generally used for read-only inspection. Tools that create, update, patch, insert, unlink, import, delete, resolve, upload, run or stop can affect project data or execution. These actions should require explicit authorization and human confirmation.

Can an AI agent create, edit and run BugBug tests through MCP?

Yes. An authorized agent can create tests and steps, update existing definitions, organize reusable components and start individual test or suite runs. The agent should first inspect the relevant project context and existing assets, then confirm the requested scope before making changes or starting execution.

How can an AI agent diagnose a failed test with BugBug MCP tools?

The agent can inspect the test run, retrieve details of the failed step and query the captured DOM snapshot. It can also use available screenshots, console logs, network logs and error details to classify the failure. It should return the supporting evidence and propose the smallest fix before changing the test.

Can an AI agent review visual regression failures through BugBug MCP?

Yes. BugBug MCP tools can access visual regression reference screenshots and help evaluate observed differences. The agent can describe what changed, estimate whether it is a product regression and recommend an action. It should not accept, reject or delete reference screenshots without explicit human approval.

Can BugBug MCP import tests from YAML or ZIP files?

Yes. The bugbug_import_test tool can import a BugBug test from YAML or ZIP. Before importing, the agent should validate the definition, variables, selectors, components and secret handling, then report any problems or risks and wait for authorization.