php-container-test-mcp

An MCP (Model Context Protocol) server that lets AI agents run PHP unit and integration tests inside Docker containers — no local PHP or Composer installation required on the host.

What it does

Exposes two MCP tools:

• run_php_tests — runs the full test suite
• run_php_test_file — runs a single test file

Both execute docker run --rm -v <host_path>:<container_path> -w <container_path> <image> composer <command> [-- <test_file>] and return the full stdout + stderr so the caller can evaluate pass/fail.

Prerequisites

• Node.js ≥ 18
• Docker installed and running on the host
• A Docker image that includes PHP, Composer, and a Composer script for running tests (e.g. phpunit, pest)

Example composer.json scripts section inside your PHP image

"scripts": {
  "test": "vendor/bin/phpunit",
  "test:unit": "vendor/bin/phpunit --testsuite unit",
  "test:integration": "vendor/bin/phpunit --testsuite integration"
}

Installation

Via npm (recommended)

npm install -g php-container-test-mcp

From source

git clone https://github.com/your-user/php-container-test-mcp
cd php-container-test-mcp
npm install

Registering with Claude Code

Add the server to your project's .mcp.json for project-scoped access, or to ~/.claude/claude_desktop_config.json for global access.

The server accepts named arguments to configure defaults. All three can also be overridden per tool call.

| Argument | Description | Default | |---|---|---| | --container | Docker image name | (required) | | --command | Composer script name to execute | test | | --host-path | Host project path to mount | current working directory | | --container-path | Mount path inside the container | /var/www |

Using the npm package (after npm install -g)

{
  "mcpServers": {
    "php-container-test": {
      "command": "php-container-test-mcp",
      "args": ["--container=my-php-app:latest", "--command=test", "--host-path=/home/user/my-project", "--container-path=/var/www"]
    }
  }
}

Using npx (no install required)

{
  "mcpServers": {
    "php-container-test": {
      "command": "npx",
      "args": ["-y", "php-container-test-mcp", "--container=my-php-app:latest", "--command=test", "--host-path=/home/user/my-project", "--container-path=/var/www"]
    }
  }
}

From source (local path)

{
  "mcpServers": {
    "php-container-test": {
      "command": "node",
      "args": ["/absolute/path/to/php-container-test-mcp/src/index.js", "--container=my-php-app:latest", "--command=test", "--host-path=/home/user/my-project", "--container-path=/var/www"]
    }
  }
}

Then restart Claude Code. The run_php_tests and run_php_test_file tools will be available automatically.

Tool reference

run_php_tests — run the full test suite

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | container_name | string | Yes | server arg | Docker image to run (e.g. my-php-app:latest) | | command | string | No | "test" | Composer script name to execute | | host_path | string | No | server arg or cwd | Absolute path to the project on the host to mount into the container | | container_path | string | No | server arg or /var/www | Path inside the container where the project will be mounted |

run_php_test_file — run a single test file

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | container_name | string | Yes | server arg | Docker image to run (e.g. my-php-app:latest) | | test_file | string | Yes | — | Path to the test file inside the container (e.g. tests/Unit/UserTest.php) | | command | string | No | "test" | Composer script name to execute | | host_path | string | No | server arg or cwd | Absolute path to the project on the host to mount into the container | | container_path | string | No | server arg or /var/www | Path inside the container where the project will be mounted |

Example prompts

Run all tests:

Run the tests for the my-php-app:latest container.

Run only unit tests using a specific Composer script:

Run only the unit tests using the test:unit script for container my-php-app:latest.

Run a single test file:

Run tests/Unit/UserTest.php in the my-php-app:latest container.

Override mount paths:

Run the tests for my-php-app:latest, mounting /home/user/my-project on the host to /app inside the container.

Example tool calls

run_php_tests — full suite with defaults:

{
  "container_name": "my-php-app:latest"
}

run_php_tests — specific Composer script:

{
  "container_name": "my-php-app:latest",
  "command": "test:unit"
}

run_php_test_file — single test file:

{
  "container_name": "my-php-app:latest",
  "test_file": "tests/Unit/UserTest.php"
}

run_php_tests — override mount paths:

{
  "container_name": "my-php-app:latest",
  "host_path": "/home/user/my-project",
  "container_path": "/app"
}

How it works

1. The server is launched by the MCP host (Claude Code) and communicates over stdin/stdout using the JSON-RPC 2.0 MCP protocol.
2. When a tool is called, the server executes:

   docker run --rm -v <host_path>:<container_path> -w <container_path> <image> composer <command> [-- <test_file>]

3. --rm ensures the container is automatically removed after each run.
4. The combined stdout + stderr is returned to the calling agent.

Troubleshooting

| Problem | Solution | |---------|----------| | docker: command not found | Ensure Docker is installed and in $PATH for the user running the MCP server | | Unable to find image '...' locally | Pull the image first: docker pull <image> | | Script "test" is not defined | Add a test script to composer.json inside your Docker image | | No output returned | The container may have exited immediately — check the image entrypoint | | Tests time out for large suites | The server uses a 10 MB output buffer; the process itself has no hard timeout — Docker will run until the suite finishes |

License

MIT