MCP Deploy

mcp-deploy

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

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

安装

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

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

______________________________________________________________________

目录

• 运作原理
• 快速开始
• 用法

- 推送图像 - 多个服务器 - MCP工具 - REST API - - Web仪表板

• 服务器

- 安装什么 - 曝光模式 - 配置 - 升级 · 卸载 - 安全

• 参考

- 建筑 - 发展 - 如何比较 - 贡献

______________________________________________________________________

运作原理

┌─────────────────┐       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 在您的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并喜欢非交互式设置的用户：

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

   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

1. 创建一个 .env 文件：

   cat > .env /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客户端使用，全部通过自然语言管理。

部署参数

______________________________________________________________________

REST API

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

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

通过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 Actions集成
• **** --一个免费的私人回购，得到广泛支持
• 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中运行：

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

______________________________________________________________________

MCP服务器曝光模式

安装程序询问应如何访问MCP服务器（仪表板、API、MCP端点）。这只影响MCP服务器——部署的应用程序始终使用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上：

编辑后 .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 （定时安全比较）
• 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.访问

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

docker restart mcp-deploy-server

开发人员配置

用环境变量覆盖默认值：

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

______________________________________________________________________

如何比较

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

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

______________________________________________________________________

贡献

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

许可证

麻省理工学院