Detox

Detox MCP is a server that connects Detox mobile testing workflows with Claude Code, enabling you to manage configurations, generate test code, run Detox E2E tests, and access device lists and API references directly from your MCP client. It streamlines building, validating, and executing Detox tests within your development workflow.

How to use

You will interact with Detox MCP through an MCP client to run tests, generate test code, and manage configurations. Use the provided slash prompts in Claude Code to perform common workflows, such as running tests, generating test code, or initializing Detox in your project. The server exposes tools for test execution, configuration handling, code generation, and device listing, all accessible via your MCP client.

How to install

# Install the MCP server globally
npm install -g detox-mcp

# Or install locally in your project
npm install detox-mcp

Configuration and getting started

Configure Detox MCP in your project by creating a configuration file that tells Claude Code how to start and communicate with the MCP server.

{
  "mcpServers": {
    "detox": {
      "command": "npx",
      "args": ["detox-mcp"],
      "env": {
        "DETOX_PROJECT_PATH": "/path/to/your/react-native/project"
      }
    }
  }
}

Devices and resources

Detox MCP can list available iOS simulators and Android emulators, and provides access to Detox configurations, test files, and API references through contextual resources.

Prompts (Slash Commands)

Use the slash prompts to perform common tasks like running tests, generating tests from descriptions, setting up Detox in your project, or debugging failing tests.

Examples

Run tests on your configured iOS simulator by asking Claude Code to execute your Detox tests. Generate a Detox test for a specific flow by describing the test, and Claude Code will create the test file for you. List available Detox configurations to understand what you can run.

Prerequisites

• Node.js 18+
• Detox installed in your React Native project
• For iOS: Xcode and applesimutils
• For Android: Android SDK and emulator

Environment variables

The following environment variable is used by the server to locate your project. It should point to the root of your React Native project.

Development

# Clone the repository (if you are contributing)
git clone https://github.com/your-username/detox-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Notes

Only use MCP commands and URLs that are explicitly shown in code blocks or config examples. Do not assume remote endpoints unless they are clearly provided as part of a config or command example.

Security and maintenance

Keep Node.js and Detox dependencies up to date. Manage access to your Detox project path and sensitive environment variables to prevent leakage in shared environments.

Troubleshooting

If you encounter issues starting the MCP server, verify that your environment variable DETOX_PROJECT_PATH is set correctly and that Detox is installed in your project. Check that the command and arguments in your mcpServers configuration match the examples exactly.

Available tools

detox_build

Build the app for Detox testing.

detox_test

Run Detox end-to-end tests with full options.

detox_init

Initialize Detox in a project.

detox_read_config

Read and parse the Detox configuration file.

detox_list_configurations

List available Detox configurations.

detox_validate_config

Validate the Detox configuration.

detox_create_config

Generate a new Detox configuration.

detox_generate_test

Generate a complete Detox test file.

detox_generate_matcher

Generate element matcher code.

detox_generate_action

Generate action code for Detox interactions.

detox_generate_expectation

Generate expectation code for Detox assertions.

detox_list_devices

List iOS simulators and Android emulators.