Magento Cloud MCP Server

mcp-magento-cloud

适用于 Adobe Commerce Cloud 的 MCP（模型上下文协议）服务。让 AI Agent 能够与 Magento Cloud 项目交互——查询数据库、读取日志、列出环境、检查活动等。

无需 PHP CLI——直接使用 REST API 和 SSH。

版本

版本	描述	要求
v2.x（最新）	直接使用 REST API 和 SSH。支持浏览器登录或 API token。	Node.js 20+、ssh 二进制文件
v1.x	封装 magento-cloud PHP CLI。	Node.js 20+、已安装 magento-cloud CLI

使用指定版本

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

# v1.x (requires magento-cloud CLI)
npx -y [email protected]

前置条件（v2.x）

• Node.js 20+
• ssh 二进制文件——Linux/macOS 默认提供

快速开始

身份验证

自动浏览器登录（推荐）

无需设置。首次使用任意工具时，会自动打开浏览器，通过 Adobe/Magento 账户进行 OAuth2 登录。凭据会保存在本地 ~/.config/mcp-magento-cloud/credentials.json 中，并自动刷新。

你也可以手动登录：

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

API token（替代方式）

如果你更倾向于使用 API token（例如用于 CI/CD），请在 https://accounts.magento.cloud/user/api-tokens 创建一个，并将其作为环境变量（MAGENTO_CLOUD_CLI_TOKEN）传入。设置 token 后，将跳过浏览器登录。

安全提示： API token 可授予对账户有权访问的所有项目的完全访问权限。请将其视为敏感密钥。如果 token 泄露，请立即在上方的 URL 撤销。

配置 MCP 客户端

Kilo

在 ~/.config/kilo/kilo.json 中：

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

如果使用 API token 而非浏览器登录，请添加 environment 键：

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

Claude Desktop

在 claude_desktop_config.json 中：

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

Gemini CLI

在 ~/.gemini/settings.json 中：

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

可用工具

REST API 工具

工具	描述
list_projects	列出当前用户可访问的所有项目
list_environments	列出项目的所有环境
get_environment_info	获取环境的详细信息
get_environment_urls	获取环境的公开 URL
list_activities	按筛选条件列出近期活动
get_activity_log	显示活动的完整日志
list_variables	列出项目或环境变量
list_services	列出服务及其版本和磁盘分配情况

SSH 工具

工具	描述
execute_sql	在远程数据库上执行只读 SQL 查询
get_environment_logs	读取服务器日志（部署、错误、cron 等）
get_environment_relationships	获取服务连接详细信息（主机、端口、凭据）
list_log_types	列出可用的日志类型

写入工具

工具	描述
set_cloud_config	通过 SSH 使用 bin/magento config:set 设置 Magento 配置值（支持 scope/scope_code 和加密值）。在 production 环境中禁止执行。
create_branch	从 integration 克隆并创建新的环境分支
push_branch	使用 SSH 证书身份验证，将本地 git 分支推送到项目

安全性

• SQL 查询经过验证——仅允许 SELECT、SHOW、DESCRIBE 和 EXPLAIN
• 会去除 SQL 注释并阻止多条语句，以防止注入
• 生产环境受保护——set_cloud_config 拒绝在 production 环境中运行；此类更改必须手动完成
• SSH 身份验证使用由 Magento Cloud API 签署的临时 Ed25519 证书
• 浏览器登录会在本地以 0600 权限保存刷新 token
• API token 应视为敏感密钥——它们可授予对所有项目的完全访问权限

使用 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

开发

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

许可证

MIT