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.

Related MCP server: Arthur

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.

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

run_php_test_file — run a single test file

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

License

MIT