Content
# Detox MCP
An MCP (Model Context Protocol) server for integrating the [Detox](https://github.com/wix/Detox) mobile testing framework with Claude Code.
## Features
- **Test Execution**: Build and run Detox E2E tests with full options
- **Configuration Management**: Read, validate, and generate Detox configurations
- **Code Generation**: Generate test code, matchers, actions, and expectations
- **Device Management**: List iOS simulators and Android emulators
- **Resources**: Access configuration, devices, tests, and API reference
- **Prompts**: Slash commands for common workflows
## Installation
```bash
npm install -g detox-mcp
```
Or install locally in your project:
```bash
npm install detox-mcp
```
## Usage with Claude Code
### Add to Claude Code
```bash
# Add globally
claude mcp add detox-mcp
# Or with npx
claude mcp add --transport stdio detox-mcp -- npx detox-mcp
```
### Project Configuration
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"detox": {
"command": "npx",
"args": ["detox-mcp"],
"env": {
"DETOX_PROJECT_PATH": "/path/to/your/react-native/project"
}
}
}
}
```
## Available Tools
### Test Execution
| Tool | Description |
|------|-------------|
| `detox_build` | Build app for Detox testing |
| `detox_test` | Run E2E tests with full options |
| `detox_init` | Initialize Detox in a project |
### Configuration
| Tool | Description |
|------|-------------|
| `detox_read_config` | Read and parse .detoxrc.js |
| `detox_list_configurations` | List available configurations |
| `detox_validate_config` | Validate configuration |
| `detox_create_config` | Generate new configuration |
### Code Generation
| Tool | Description |
|------|-------------|
| `detox_generate_test` | Generate complete test file |
| `detox_generate_matcher` | Generate element matcher code |
| `detox_generate_action` | Generate action code |
| `detox_generate_expectation` | Generate expectation code |
### Devices
| Tool | Description |
|------|-------------|
| `detox_list_devices` | List iOS simulators and Android emulators |
## Resources
Access contextual data via the resource URIs:
| URI | Description |
|-----|-------------|
| `detox://config` | Current Detox configuration |
| `detox://devices` | Available simulators/emulators |
| `detox://tests` | Test file listings |
| `detox://api/matchers` | Matchers API reference |
| `detox://api/actions` | Actions API reference |
| `detox://api/expectations` | Expectations API reference |
| `detox://api/device` | Device API reference |
## Prompts (Slash Commands)
Use these prompts in Claude Code for common workflows:
| Prompt | Description |
|--------|-------------|
| `/detox-test` | Run tests with smart defaults |
| `/detox-generate` | Generate test from description |
| `/detox-setup` | Initialize Detox in project |
| `/detox-debug` | Debug failing tests |
## Examples
### Run Tests
```
Ask Claude: "Run my Detox tests on iOS simulator"
```
Claude will use `detox_build` and `detox_test` tools to execute your tests.
### Generate Test Code
```
Ask Claude: "Generate a Detox test for the login flow"
```
Claude will use `detox_generate_test` to create test code.
### Check Configuration
```
Ask Claude: "What Detox configurations are available?"
```
Claude will use `detox_list_configurations` to show available configs.
## Requirements
- Node.js 18+
- Detox installed in your React Native project
- For iOS: Xcode and applesimutils
- For Android: Android SDK and emulator
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `DETOX_PROJECT_PATH` | Path to React Native project | Current directory |
## Development
```bash
# Clone the repo
git clone https://github.com/your-username/detox-mcp
# Install dependencies
npm install
# Build
npm run build
# Run in development
npm run dev
```
## License
MIT
