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

bash

# 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:

Terminal

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:

config.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:

config.json

{
  "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:

config.json

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

Gemini CLI

In ~/.gemini/settings.json:

config.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

bash

# 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

bash

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