使用说明

mcp-deploy

地球上最轻量级的PaaS。从任何MCP客户端将Docker容器部署到您的VPS。没有数据库，没有臃肿——只需部署。

网站 · 快速开始 · MCP工具 · REST API

演示视频： 观看完整演示在项目网站上。

安装

在任何Linux VPS上运行此程序——在一分钟内安装所有内容：

curl -fsSL https://raw.githubusercontent.com/ddalcu/mcp-deploy/main/install.sh | bash

运作原理

┌─────────────────┐       HTTPS        ┌─────────────────────────────────────┐
│  Claude Code /  │ ────────────────── │          Your VPS                   │
│  Cursor / any   │   MCP Protocol     │                                     │
│  MCP Client     │      /mcp          │  Traefik ──→ MCP Server (:3000)     │
└─────────────────┘                    │     │                               │
                                       │     ├──→ my-app.deploy.example.com  │
┌─────────────────┐    HTTP (direct)   │     ├──→ my-api.deploy.example.com  │
│  GitHub Actions │ ────────────────── │     └──→ blog.deploy.example.com    │
│  / CI/CD / curl │   REST API /api    │                                     │
└─────────────────┘                    └─────────────────────────────────────┘

交通处理SSL（每个子域自动生成Let's Encrypt证书），并将每个子域路由到正确的容器
MCP服务器 接收工具调用可流式传输的HTTP 并管理Docker容器
无数据库 --Docker是真理之源
不需要注册表 --直接推送图像或从GHCR/DockerHub拉取图像

快速开始

您需要一个具有公共IP的Linux VPS。任何供应商都可以工作——如果你还没有， Hetzner给你20美元的信用额度.

注： Proxmox/LXC注意：如果你想在Proxmox/XXC上运行它，请确保它在VM中，而不是LXC中。

1.设置DNS

创建两个指向您的VPS IP的DNS A记录：

记录	类型	值	目的
`deploy.example.com` A. `YOUR_VPS_IP`	MCP服务器(`mcp.deploy.example.com`)
`*.deploy.example.com` A. `YOUR_VPS_IP`	所有已部署的应用程序(`myapp.deploy.example.com`等等）

注：通配符记录(*)必须包含点和星号前缀——请完全按照以下方式输入 *.deploy.example.com 在您的DNS提供商中。这是与基本域分离的记录。

2.在您的VPS上安装

使用以下命令运行安装程序卷曲:

curl -fsSL https://raw.githubusercontent.com/ddalcu/mcp-deploy/main/install.sh | bash

或与 wget:

wget -qO- https://raw.githubusercontent.com/ddalcu/mcp-deploy/main/install.sh | bash

安装程序要求两件事： 基础域名 （例如。 deploy.example.com，没有 * 或前导点）以及 电子邮件 （Let’s Encrypt）。就是这样，它生成一个API密钥并启动一切。

替代方案：Docker编写安装

对于已经拥有Docker并喜欢非交互式设置的用户：

创建目录并下载撰写文件：

mkdir -p /opt/mcp-deploy && cd /opt/mcp-deploy
curl -fsSL https://raw.githubusercontent.com/ddalcu/mcp-deploy/main/docker-compose.yml -o docker-compose.yml

创建一个 .env 文件：

cat > .env <<EOF
DOMAIN=deploy.example.com
ACME_EMAIL=you@example.com
API_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

启动堆栈：

docker network create web 2>/dev/null; docker compose up -d

可选： 集 MCP_TRAEFIK=false 和 DIRECT_PORT=8080 在 .env 更改MCP服务器的暴露方式。看曝光模式了解详情。

3.添加到您的MCP客户端

将安装程序输出的配置复制到MCP客户端设置中。

克劳德代码：

claude mcp add deploy https://mcp.deploy.example.com/mcp \
  -t http -s user \
  -H "Authorization: Bearer YOUR_API_KEY"

这 -s user flag使其在所有项目中都可用。添加后重新启动Claude Code。

4.部署一些东西

在Claude Code中打开任何项目，然后说：

“部署nginx:alpine作为hello”

访问 https://hello.deploy.example.com --它使用SSL。

推送图像

选项A：直接推送（无需注册表）

在本地构建并将图像直接发送到您的VPS：

docker build -t my-app:latest .
docker save my-app:latest | curl -X POST -T - \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://mcp.deploy.example.com/upload

然后部署它：

“部署我的应用程序：最新版本为端口3000上的应用程序”

选项B：从外部注册表中提取

使用任何注册表。公共图像只是工作：

“在端口80上部署nginx:alpine作为文档”

对于私有注册表，请传递凭据：

“部署ghcr.io/myorg/my应用程序：最新版本为端口3000上的我的应用程序，使用注册表身份验证用户名myuser密码ghp_abc123”

多个服务器

在任意数量的VPS服务器上安装。将每个添加为单独的MCP服务器条目：

{
  "mcpServers": {
    "deploy-prod": {
      "type": "streamable-http",
      "url": "https://mcp.prod.example.com/mcp",
      "headers": { "Authorization": "Bearer PROD_KEY" }
    },
    "deploy-staging": {
      "type": "streamable-http",
      "url": "https://mcp.staging.example.com/mcp",
      "headers": { "Authorization": "Bearer STAGING_KEY" }
    }
  }
}

然后指定哪个服务器： “部署我的应用程序以部署登台”

MCP工具

九种工具，可供任何MCP客户端使用，全部通过自然语言管理。

工具	说明
`deploy`	部署或重新部署具有自动SSL和子域路由的Docker映像
`deploy-static`	部署一个静态HTML/CSS/JS站点——不需要Docker镜像
`list`	列出所有托管部署
`logs`	获取容器日志
`status`	详细的应用程序信息——CPU、内存、正常运行时间、重启次数
`stop`	停止正在运行的应用程序（容器保留）
`start`	启动已停止的应用程序
`remove`	永久删除应用程序及其容器
`upload-image`	将本地构建的Docker镜像推送到您的VPS——无需注册表

部署参数

参数	类型	必填	描述
`name`	string	yes	应用程序名称--成为子域(`name.domain.com`)
`image`	string	yes	Docker镜像（例如。 `nginx:alpine`, `ghcr.io/user/repo:v1`)
`port`	number	no	应用程序在容器内监听的端口。从图像中自动检测到 `EXPOSE` 如果没有提供指令。
`env`	object	否	环境变量(`{ "KEY": "value" }`)
`registry_auth`	对象	否	`{ "username": "...", "password": "..." }` 对于私人注册机构
`volumes`	string[]	no	命名卷装载(`["data:/app/data"]`)
`command`	string	no	覆盖容器的默认命令

REST API

所有MCP工具都可以作为标准REST端点使用，不需要LLM或MCP客户端。从GitHub操作、shell脚本或任何HTTP客户端使用这些。

所有端点都需要 Authorization: Bearer YOUR_API_KEY.

方法	路径	描述
`POST`	`/api/deploy`	部署或重新部署Docker镜像
`GET`	`/api/apps`	列出所有已部署的应用程序
`GET`	`/api/apps/:name`	获取详细的应用程序状态
`GET`	`/api/apps/:name/logs`	获取应用程序日志
`POST`	`/api/apps/:name/stop`	停止应用程序
`POST`	`/api/apps/:name/start`	启动已停止的应用程序
`DELETE`	`/api/apps/:name`	删除应用程序
`POST`	`/upload`	上传Docker镜像（二进制流）
`POST`	`/deploy-static/:name`	部署静态站点（tar.gz）

通过REST部署

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "image": "nginx:alpine", "port": 80}' \
  https://mcp.deploy.example.com/api/deploy

答复：

{"name": "my-app", "url": "https://my-app.deploy.example.com", "image": "nginx:alpine", "container": "mcp-deploy-my-app", "status": "running"}

列出应用程序

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://mcp.deploy.example.com/api/apps

# Filter: ?status=running or ?status=stopped

应用程序状态、日志、停止、启动、删除

# Status
curl -H "Authorization: Bearer $KEY" https://mcp.example.com/api/apps/my-app

# Logs (optional: ?tail=50&since=1h)
curl -H "Authorization: Bearer $KEY" https://mcp.example.com/api/apps/my-app/logs

# Stop
curl -X POST -H "Authorization: Bearer $KEY" https://mcp.example.com/api/apps/my-app/stop

# Start
curl -X POST -H "Authorization: Bearer $KEY" https://mcp.example.com/api/apps/my-app/start

# Remove (optional: ?remove_volumes=true)
curl -X DELETE -H "Authorization: Bearer $KEY" https://mcp.example.com/api/apps/my-app

GitHub操作

对于CI/CD，您通常会从注册表推送映像，而不是直接上传。推荐注册中心：

GitHub容器注册表（GHCR） --免费公开存储库，与GitHub Actions集成
Docker 中心 --一个免费的私人回购，得到广泛支持
ttl.sh --匿名、临时注册表（图像在数小时后过期）——非常适合预览和测试

从注册表部署（推荐）

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

      - name: Deploy to VPS
        run: |
          curl -fsSL -X POST \
            -H "Authorization: Bearer ${{ secrets.DEPLOY_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "name": "my-app",
              "image": "ghcr.io/${{ github.repository }}:latest",
              "port": 3000,
              "registry_auth": {
                "username": "${{ github.actor }}",
                "password": "${{ secrets.GITHUB_TOKEN }}"
              }
            }' \
            https://mcp.${{ secrets.DEPLOY_DOMAIN }}/api/deploy

使用直接映像上传进行部署（无需注册表）

如果您不想使用注册表，可以直接上传图像。这需要直接端口接入为了获得最佳效果。

      - name: Build and upload image
        run: |
          docker build -t my-app:latest .
          docker save my-app:latest | curl -fsSL -X POST -T - \
            -H "Authorization: Bearer ${{ secrets.DEPLOY_KEY }}" \
            http://${{ secrets.VPS_IP }}:8080/upload

      - name: Deploy
        run: |
          curl -fsSL -X POST \
            -H "Authorization: Bearer ${{ secrets.DEPLOY_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"name": "my-app", "image": "my-app:latest", "port": 3000}' \
            http://${{ secrets.VPS_IP }}:8080/api/deploy

部署静态站点

      - name: Deploy static site
        run: |
          tar -czf site.tar.gz -C ./dist .
          curl -fsSL -X POST \
            -H "Authorization: Bearer ${{ secrets.DEPLOY_KEY }}" \
            -H "Content-Type: application/gzip" \
            --data-binary @site.tar.gz \
            https://mcp.${{ secrets.DEPLOY_DOMAIN }}/deploy-static/my-site

Web仪表板

服务器在根URL处包含一个内置的web仪表板(/).它显示了所有已部署的应用程序及其状态、资源使用情况和日志——不需要MCP客户端。

认证：输入要登录的API密钥（保存在 localStorage)
应用程序表：名称、状态（绿色/红色徽章）、图像、URL、CPU、内存
日志：单击任意行展开并查看最后50行日志
自动刷新：每30秒轮询一次
深色主题，无外部依赖，适用于移动设备

访问它在 https://mcp.deploy.example.com （生产）或 http://localhost:3000 （本地开发）。

你的VPS上安装了什么

/opt/mcp-deploy/
├── .env                  ← your config + API key (chmod 600)
└── docker-compose.yml    ← the stack definition

两个文件。其他一切都在Docker中运行：

容器	图像	用途
`mcp-deploy-traefik`	`traefik:v3.3`	反向代理+自动SSL
`mcp-deploy-server`	`ghcr.io/ddalcu/mcp-deploy`	MCP服务器

加上a traefik-certs Let's Encrypt证书和 web 所有容器共享的网络。

MCP服务器曝光模式

安装程序询问应如何访问MCP服务器（仪表板、API、MCP端点）。这只影响MCP服务器——部署的应用程序始终使用Traefik进行子域路由。

模式	MCP服务器访问	已部署的应用程序
仅限域名（默认）	`https://mcp.domain.com` 通过Traefik
仅限港口	`http://IP:PORT` 直接访问	通过Traefik
两者	域+直接端口	通过Traefik

仅限港口 当您前面有自己的反向代理，或者只需要API/CI访问而不需要MCP服务器本身的子域时，会很有用。

要在安装后更改模式，请编辑 /opt/mcp-deploy/.env:

# Domain only (default) — remove MCP_TRAEFIK and DIRECT_PORT lines

# Port only
MCP_TRAEFIK=false
DIRECT_PORT=8080

# Both
DIRECT_PORT=8080

对于 仅限港口 或两者，创建 /opt/mcp-deploy/docker-compose.override.yml:

services:
  mcp-server:
    ports:
      - "${DIRECT_PORT}:3000"

然后重新启动：

cd /opt/mcp-deploy && docker compose up -d

安全说明： 直接端口是HTTP（不是HTTPS）。仅将其用于已知VPS IP的服务器到服务器通信（CI/CD）。所有终结点仍然需要API密钥。

配置

所有配置都在 /opt/mcp-deploy/.env 在VPS上：

变量	描述	默认值
`DOMAIN`	所有服务的基本域	（必填）
`ACME_EMAIL`	让我们加密通知电子邮件	（必填）
`API_KEY`	MCP服务器身份验证的承载令牌	（自动生成）
`MCP_IMAGE`	覆盖MCP服务器Docker镜像	`ghcr.io/ddalcu/mcp-deploy:latest`
`MCP_TRAEFIK`	通过Traefik路由MCP服务器	`true`
`DIRECT_PORT`	通过IP（无SSL）暴露此端口上的MCP服务器	（残疾）

编辑后 .env，重新启动堆栈：

cd /opt/mcp-deploy && docker compose up -d

升级

cd /opt/mcp-deploy && docker compose pull && docker compose up -d

这将提取最新的MCP服务器映像并重新创建容器。您的配置(.env)部署的应用程序和SSL证书不受影响。

卸载

cd /opt/mcp-deploy && docker compose down -v
rm -rf /opt/mcp-deploy
docker network rm web

安全

所有流量都是通过Traefik+Let’s Encrypt的HTTPS（通过HTTP-01挑战自动生成每个子域证书）
MCP和上传端点需要 Authorization: Bearer <token> （定时安全比较）
API密钥是用生成的 openssl rand -hex 32 （256位）
.env 文件是 chmod 600 （仅root可读）
卷装载仅限于命名卷（无主机路径装载）
基础结构容器名称是保留的，不能通过部署覆盖
上传端点强制执行2 GB的大小限制

建筑

graph LR
  subgraph Clients
    CC[Claude Code / Cursor]
    CI[GitHub Actions / curl]
  end

  subgraph VPS
    T[Traefik]
    MCP[MCP Server :3000]
    D[(Docker)]

    T -- "/mcp" --> MCP
    T -- "/api/*" --> MCP
    MCP -- "manage containers" --> D

    T -- "*.domain.com" --> Apps
    Apps[Deployed Apps] --> D
  end

  CC -- "MCP Protocol (HTTPS)" --> T
  CI -- "REST API (HTTPS)" --> T

server/src/
├── index.ts        ← Express + MCP Streamable HTTP transport + /upload endpoint
├── api.ts          ← REST API router (/api/*) for CI/CD
├── auth.ts         ← Bearer token middleware (timing-safe)
├── config.ts       ← Environment variable config
├── dashboard.ts    ← Web dashboard HTML (served at GET /)
├── docker.ts       ← Dockerode singleton + pull/load/list helpers
├── labels.ts       ← Traefik label generator
├── validation.ts   ← Shared app name validation + reserved names
└── tools/
    ├── deploy.ts   ← Pull or use local image, create container with Traefik labels
    ├── list.ts     ← Query Docker for containers labeled mcp-deploy.managed=true
    ├── logs.ts     ← Container log retrieval
    ├── status.ts   ← Container inspect + live CPU/memory stats
    ├── stop.ts     ← Stop container
    ├── start.ts    ← Start container
    └── remove.ts   ← Stop + remove container

设计原则：

Docker是数据库——没有SQLite，没有JSON状态文件，没有同步问题
Traefik通过Docker标签自动发现容器——无需重新加载配置
每个工具都是一个文件（SRP）——无需接触现有代码即可轻松添加新工具
无状态身份验证——每个请求都独立验证，没有会话

发展

本地开发组合文件使用自签名TLS、源代码挂载和实时重新加载在您的计算机上运行全栈（Traefik+MCP服务器）。与Docker、Podman和OrbStack兼容。

1.添加主机条目

# macOS / Linux
echo "127.0.0.1 mcp.mcp.local" | sudo tee -a /etc/hosts

对于您在本地部署的每个应用程序，也添加其子域（例如。 127.0.0.1 my-app.mcp.local).

2.启动堆栈

git clone https://github.com/ddalcu/mcp-deploy.git
cd mcp-deploy
docker compose -f docker-compose.dev.yml up

启动输出显示仪表板URL和API键：

  Dashboard: http://localhost:3000
  API Key:   devkey

3.访问

URL	描述
`http://localhost:3000`	直接访问（绕过Traefik）
`http://mcp.mcp.local`	通过Traefik（HTTP）
`https://mcp.mcp.local`	通过Traefik（HTTPS，接受自签名证书警告）

源文件从以下位置绑定挂载 server/src/ --编辑并重新启动 mcp-deploy-server 用于获取更改的容器：

docker restart mcp-deploy-server

开发人员配置

用环境变量覆盖默认值：

DOMAIN=mydev.local API_KEY=mysecret docker compose -f docker-compose.dev.yml up

变量	默认值	描述
`DOMAIN`	`mcp.local`	路由的基本域
`API_KEY`	`devkey`	用于身份验证的承载令牌

如何比较

	MCP Docker服务器	自托管PaaS	mcp部署
远程VPS部署	否	是	是
MCP协议（AI原生）	是	否	是
自动SSL+子域	否	是	是
无数据库/最小	N/A	否（大多数有DB）	是
直接图像推送	否	部分	是
用于CI/CD的REST API	否	是	是

MCP Docker服务器 喜欢 mcp服务器docker 和 docker mcp 让AI在本地管理Docker，但不要部署到远程服务器。

自托管PaaS 平台如冷却, 医生, CapRover，以及多克普莱使用web UI或CLI将容器部署到您的VPS，但没有MCP集成。

mcp-deploy将mcp本地AI控制与远程PaaS部署和零数据库极简主义相结合。

贡献

欢迎捐款。请先打开一个问题，讨论您想更改的内容。

许可证

麻省理工学院