Warp Magento MCP Server

A Model Context Protocol (MCP) server that integrates AI assistants with Warp Engine + Magento 2 Docker development environments. This server enables AI assistants to interact directly with your Warp-managed Magento projects, running CLI commands, database queries, and managing containers.

Features

• Environment Management: Start/stop projects (warp start / warp stop)
• Environment Info: List running containers and service configuration (warp ps, warp info)
• Database Operations: Execute SQL queries in the project database
• PHP Scripts: Run PHP scripts inside the container
• Magento CLI: Execute bin/magento commands
• Unit Testing: Run PHPUnit tests inside the container
• Composer: Manage dependencies
• Project Init: Initialize a Warp project non-interactively

Prerequisites

• Warp Engine: Each project must have the ./warp script at its root
• Docker: Required for Warp Engine to function
• Node.js: Version 18.0.0 or higher

Installation

npm install -g warp-magento-mcp-server

Or use directly with npx (no install needed):

npx warp-magento-mcp-server

Configuration

For Warp (Recommended)

Create or update ~/.warp/.mcp.json:

{
  "mcpServers": {
    "warp-magento": {
      "command": "npx",
      "args": ["warp-magento-mcp-server"]
    }
  }
}

Warp will auto-spawn the server on startup. You can manage it from Settings → Agents → MCP servers.

Alternatively, use the built-in /agent-add-mcp slash command inside Warp to let the agent configure it for you.

Using a local clone instead of npx

If you prefer to run from source:

{
  "mcpServers": {
    "warp-magento": {
      "command": "node",
      "args": ["/absolute/path/to/warp-mcp-server/server.js"],
      "working_directory": "/absolute/path/to/warp-mcp-server"
    }
  }
}

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "warp-magento": {
      "command": "npx",
      "args": ["warp-magento-mcp-server"]
    }
  }
}

Available Tools

warp_list_environments

Lists container status and service info for a Warp project (warp ps + warp info).

Parameters:

• project_path (required): Path to the project directory

warp_start_project

Starts the project environment (warp start).

Parameters:

• project_path (required): Path to the project directory

warp_stop_project

Stops the project environment (warp stop).

Parameters:

• project_path (required): Path to the project directory

warp_info

Shows configured values for all services — PHP, MySQL, Redis, Nginx, etc. (warp info).

Parameters:

• project_path (required): Path to the project directory

warp_db_query

Executes a SQL query in the project database via docker-compose exec.

Parameters:

• project_path (required): Path to the project directory
• query (required): SQL query to execute
• database (optional): Database name (defaults to DATABASE_NAME from project .env)

warp_php_script

Runs a PHP script inside the container.

Parameters:

• project_path (required): Path to the project directory
• script_path (required): Path to the PHP script relative to project root
• args (optional): Additional arguments to pass to the script

warp_magento_cli

Executes a bin/magento command inside the container (warp magento -T <command>).

Parameters:

• project_path (required): Path to the project directory
• command (required): Magento CLI command (without bin/magento prefix)
• args (optional): Additional arguments

Examples: cache:clean, setup:upgrade, indexer:reindex

warp_run_unit_tests

Runs PHPUnit tests inside the container.

Parameters:

• project_path (required): Path to the project directory
• config_file (optional): PHPUnit config file (auto-detects phpunit.xml.dist or phpunit.xml)
• test_path (optional): Path to specific test file or directory
• extra_args (optional): Additional PHPUnit arguments

warp_composer

Runs a Composer command inside the container (warp composer -T <command>).

Parameters:

• project_path (required): Path to the project directory
• command (required): Composer command (e.g., install, update, require vendor/package)

warp_init_project

Initializes the Warp project without the interactive wizard (warp init --no-interaction).

Parameters:

• project_path (required): Path to the project directory containing the ./warp script

Troubleshooting

• Each project must have a ./warp script at its root — this is the Warp Engine entry point
• The MCP server runs commands by executing bash ./warp <subcommand> from the project directory
• Check MCP server logs in Warp: Settings → Agents → MCP servers → View Logs

License

MIT