SnapDeploy MCP

@snapdeploy/mcp

通过 AI 助手部署和管理 SnapDeploy 容器 — Claude Code、Claude Desktop、Cursor、Windsurf、Codex CLI、Gemini CLI，或任何通过 stdio 支持 Model Context Protocol 的客户端。

只需说 “将此仓库部署到 SnapDeploy”，即可获得一个可访问的 URL。无需离开聊天，即可完成构建、查看日志、管理环境变量、托管数据库和自定义域名。

设置

1. 在 snapdeploy.dev 登录，打开 API Keys 并创建一个具有 deploy 范围的令牌（该页面会生成下方代码片段，并自动填入你的令牌）。
2. 将服务添加到客户端：

Claude Code

claude mcp add --scope user snapdeploy -e SNAPDEPLOY_API_KEY=sd_pat_your_token -- npx -y @snapdeploy/mcp

Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）、 Gemini CLI（~/.gemini/settings.json）、Claude Desktop 和其他使用 JSON 配置的客户端：

{
  "mcpServers": {
    "snapdeploy": {
      "command": "npx",
      "args": ["-y", "@snapdeploy/mcp"],
      "env": { "SNAPDEPLOY_API_KEY": "sd_pat_your_token" }
    }
  }
}

Codex CLI（~/.codex/config.toml）：

[mcp_servers.snapdeploy]
command = "npx"
args = ["-y", "@snapdeploy/mcp"]
env = { SNAPDEPLOY_API_KEY = "sd_pat_your_token" }

Claude Code 插件（令牌存储在安全存储中，而不是配置文件中）：

/plugin marketplace add AAR-Labs/snapdeploy-mcp
/plugin install snapdeploy@snapdeploy

重启会话后，snapdeploy 工具就会出现。你的仓库必须位于 GitHub 上，并且 GitHub 必须至少连接到 SnapDeploy 一次（如果尚未连接，连接器会返回链接）。

工具

范围	工具
read	list_apps get_status get_logs get_deployments check_quota list_repos detect_env_vars
deploy	deploy deploy_image set_env start_container stop_container wake_container
manage	create_database add_domain assign_always_on

范围可以嵌套（read ⊂ deploy ⊂ manage）；服务会在任何工具运行前执行范围检查。 没有删除工具，并且对于所有令牌，服务都会拒绝删除、取消订阅和更改密码的请求 — 这些操作需要由已登录控制面板或移动应用的用户执行。

预构建镜像。 deploy 会从已连接的 GitHub 仓库构建；没有镜像工具。若要运行公开的 Docker 镜像，请使用控制面板（Deploy Your Application → Docker Image），或通过 POST /api/mobile/containers 提交 name、image、imageTag、port，然后调用 POST /api/mobile/containers/{containerId}/start。镜像必须来自 Docker Hub、ghcr.io、quay.io 或 public.ecr.aws，支持 linux/amd64 或 linux/arm64，并通过 SnapDeploy 在创建时执行的策略检查；如果返回 400 Security policy violation，则不能重试。完整规则：https://snapdeploy.dev/llms-full.md

安全模型

• 绝不执行任何破坏性操作。 即使 Agent 使用相同令牌升级为直接调用 API，也会收到 403 INTERACTIVE_SESSION_REQUIRED。
• 机密信息绝不会传给模型。 环境变量的值会以 (set) 返回，凭据会被遮蔽 — 这是在服务端完成的，而不只是在此连接器中完成。
• 范围受限、会过期且可撤销的令牌，并设有独立的速率限制。在 API Keys 页面撤销令牌后，所有请求都会立即返回 401。
• 可安全重试的部署。 十分钟内发出的相同请求会返回原始部署，而不是启动另一次构建。
• 计划限制会直接传达，不会重试。 402/429 响应会附带 SnapDeploy 的消息和升级链接，并告知助手不要重试。

环境变量

变量	必需	含义
SNAPDEPLOY_API_KEY	是	有范围限制的令牌（sd_pat_…）或旧版 API 密钥
SNAPDEPLOY_READ_ONLY	否	1 表示只开放读取工具
SNAPDEPLOY_BASE_URL	否	默认为 https://snapdeploy.dev

链接

• 指南：Claude Code · Cursor · Codex / Gemini CLI · Lovable 导出
• 参考：snapdeploy.dev/docs/mcp · API
• 设计说明：为什么能够部署的 Agent 不能拥有删除权限

MIT © AAR Labs