mcp-magento-cloud

mcp-magento-cloud

MCP (Model Context Protocol) server for Adobe Commerce Cloud. Allows AI agents to interact with Magento Cloud projects — query databases, read logs, list environments, inspect activities, and more.

No PHP CLI required — uses the REST API and SSH directly.

Versions

Version	Description	Requirements
v2.x (latest)	REST API + SSH directly. Browser login or API token.	Node.js 20+, ssh binary
v1.x	Wraps the magento-cloud PHP CLI.	Node.js 20+, magento-cloud CLI installed

Using a specific version

# Latest (v2.x)
npx -y mcp-magento-cloud

# v1.x (requires magento-cloud CLI)
npx -y mcp-magento-cloud@1.0.1

Prerequisites (v2.x)

• Node.js 20+
• ssh binary — Available by default on Linux/macOS

Quick Start

Authentication

Automatic browser login (recommended)

No setup required. The first time you use any tool, a browser window will open automatically for OAuth2 login via your Adobe/Magento account. Credentials are stored locally in ~/.config/mcp-magento-cloud/credentials.json and refreshed automatically.

You can also login manually:

npx -y -p mcp-magento-cloud mcp-magento-cloud-login

API token (alternative)

If you prefer using an API token (e.g. for CI/CD), create one at https://accounts.magento.cloud/user/api-tokens and pass it as an environment variable (MAGENTO_CLOUD_CLI_TOKEN). When a token is set, browser login is skipped.

Security note: API tokens grant full access to all projects your account has access to. Treat them as sensitive secrets. If a token is compromised, revoke it immediately at the URL above.

Configure your MCP client

Kilo

In ~/.config/kilo/kilo.json:

{
  "mcp": {
    "magento-cloud": {
      "type": "local",
      "command": ["npx", "-y", "mcp-magento-cloud"]
    }
  }
}

If using an API token instead of browser login, add the environment key:

{
  "mcp": {
    "magento-cloud": {
      "type": "local",
      "command": ["npx", "-y", "mcp-magento-cloud"],
      "environment": {
        "MAGENTO_CLOUD_CLI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "magento-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-magento-cloud"]
    }
  }
}

Gemini CLI

In ~/.gemini/settings.json:

{
  "mcpServers": {
    "magento-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-magento-cloud"]
    }
  }
}

Available Tools

REST API Tools

Tool	Description
list_projects	List all projects available to the current user
list_environments	List all environments for a project
get_environment_info	Get detailed info about an environment
get_environment_urls	Get the public URLs of an environment
list_activities	List recent activities with filters
get_activity_log	Display the full log for an activity
list_variables	List project or environment variables
list_services	List services with versions and disk allocation

SSH Tools

Tool	Description
execute_sql	Execute a read-only SQL query on the remote database
get_environment_logs	Read server logs (deploy, error, cron, etc.)
get_environment_relationships	Get service connection details (host, port, credentials)
list_log_types	List available log types

Write Tools

Tool	Description
set_cloud_config	Set a Magento config value via bin/magento config:set over SSH (supports scope/scope_code and encrypted values). Blocked on the production environment.
create_branch	Create a new environment branch cloned from integration
push_branch	Push a local git branch to the project using SSH certificate auth

Security

• SQL queries are validated — only SELECT, SHOW, DESCRIBE, and EXPLAIN are allowed
• SQL comments are stripped and multiple statements are blocked to prevent injection
• Production is protected — set_cloud_config refuses to run against the production environment; such changes must be made manually
• SSH authentication uses temporary Ed25519 certificates signed by the Magento Cloud API
• Browser login stores refresh tokens locally with 0600 permissions
• API tokens should be treated as sensitive secrets — they grant full access to all projects

Testing with MCP Inspector

# Browser login will open automatically on first tool use
npx @modelcontextprotocol/inspector node dist/main.js

# Or with API token
MAGENTO_CLOUD_CLI_TOKEN=your-token npx @modelcontextprotocol/inspector node dist/main.js

Development

git clone https://github.com/juan-cinto-infracommerce/mcp-magento-cloud.git
cd mcp-magento-cloud
npm install
npm run build
npm start

License

MIT