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

```bash
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`:

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

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

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

#### Gemini CLI

In `~/.gemini/settings.json`:

```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