🚀 PaaSMCP — Agent-First Micro-PaaS & MCP Server

Turn any Linux server or Homelab into a Render / Railway experience operated directly by AI Agents via MCP (Model Context Protocol) or CLI — with zero idle RAM overhead.
🇧🇷 Leia a Documentação Completa em Português aqui (docs/PT-BR.md)

💡 Why PaaSMCP?

Self-hosted PaaS dashboards like Coolify, Dokploy, and CapRover are great for manual clicking, but they:

1. Consume 300MB–1GB+ of RAM continuously just to run their web control planes and internal databases.

2. Require manual multi-step setup for SSH deploy keys, database bindings, and Cloudflare Tunnel / Zero Trust rules.

3. Were not designed from day one to be operated by AI Agents via MCP.

PaaSMCP takes a radically lightweight, Agent-First approach:

• 0 MB Idle Daemon Overhead: Runs on-demand via MCP stdio or CLI, orchestrating native Docker Compose stacks directly on your host.

• AES-256-GCM Encrypted Secrets Vault: Secrets are encrypted at rest (/opt/homelab/paasmcp/vault/<app>.enc.json) with a 0600 master key. Values are masked in MCP outputs (sk_l****def) and can be ingested directly from files so sensitive keys never pass through LLM chat histories.

• Instant Multi-Tenant Databases: Provision isolated PostgreSQL 16 databases (db_<app> + user_<app>) or Redis 7 logical instances in 1 second, automatically injecting DATABASE_URL and REDIS_URL into the app's encrypted vault.

• Zero-Config Buildpacks: Automatically builds repositories with a custom Dockerfile or generates optimized multi-stage Dockerfiles for Node.js, Next.js, Vite/React/Astro SPAs, Python (FastAPI/Flask/Django), Go, and Static HTML.

• Built-in Web Control Plane (paasmcp-dashboard): Optional ultra-lightweight dark-mode web dashboard (protected by DASHBOARD_TOKEN + Cloudflare Zero Trust Access) that can be hosted on its own subdomain (paas.example.com) to visually deploy apps, inspect logs, manage encrypted Vault secrets, and provision databases.

• 1-Call Secure Internet Exposure: Automatically updates Cloudflare Tunnel (cloudflared) ingress rules, creates proxied CNAME DNS records, attaches Cloudflare Zero Trust Access (Email OTP) policies, or exposes privately on your Tailscale Tailnet (Tailscale Serve).

Related MCP server: ssh-alias-mcp

🏗️ Architecture

flowchart LR
    Agent["AI Agent (T3 Code / Claude / Cursor)"] <-->|Stdio JSON-RPC| MCP["PaaSMCP MCP Server & CLI"]
    
    subgraph Server ["Self-Hosted Linux Server / Homelab"]
        MCP --> Vault["AES-256-GCM Vault (.enc.json)"]
        MCP --> SSH["SSH Ed25519 Deploy Keys"]
        MCP --> Builder["Zero-Config Buildpack Engine"]
        
        subgraph Docker ["Docker Engine (homelab-network)"]
            PG[("Shared PostgreSQL 16\n127.0.0.1:5432")]
            RD[("Shared Redis 7\n127.0.0.1:6379")]
            App1["App Container 1\n127.0.0.1:4000"]
            App2["App Container 2\n127.0.0.1:4001"]
            CF["cloudflared-tunnel"]
        end
    end

    SSH -->|Clone Private Repo| GitHub["GitHub Repositories"]
    App1 --> PG
    App1 --> RD
    CF <-->|QUIC Outbound Tunnel| Cloudflare["Cloudflare Edge + Zero Trust Access"]

⚡ Quick Installation

Requirements

• Linux (Ubuntu/Debian/Fedora/Arch)

• Docker Engine & Docker Compose plugin (docker compose)

• Node.js >= 20.0.0 & git

1-Command Setup

git clone <repository-url>
cd paasmcp
./scripts/install.sh

🔌 MCP Server Configuration

Add paasmcp to your MCP client configuration (claude_desktop_config.json, Cursor, T3 Code, Windsurf, etc.):

{
  "mcpServers": {
    "paasmcp": {
      "command": "node",
      "args": ["/path/to/paasmcp/dist/mcp-server.js"]
    }
  }
}

Available MCP Tools (12 Tools)

💻 CLI Reference

# Initialize PaaSMCP and start shared Postgres & Redis clusters
paasmcp init --postgres --redis

# Configure Cloudflare Tunnel & Domain settings
paasmcp config --account-id <CF_ACCOUNT_ID> --tunnel-id <CF_TUNNEL_ID> --domain example.com --zero-trust-emails you@example.com

# Store platform tokens in the encrypted 'system' vault
paasmcp secret set system CF_API_TOKEN=your_cf_token GITHUB_TOKEN=your_gh_token

# Register SSH Deploy Key on a private GitHub repository
paasmcp github-key owner/my-private-saas

# Deploy an app from GitHub with automatic PostgreSQL provisioning
paasmcp deploy my-saas owner/my-private-saas --branch main --postgres

# Expose on https://my-saas.example.com (public or zero-trust)
paasmcp expose my-saas public my-saas

# View logs or manage container lifecycle
paasmcp logs my-saas
paasmcp restart my-saas

📚 Additional Documentation

• 🇧🇷 Guia Completo em Português (docs/PT-BR.md)

• 🏛️ Technical Architecture & Security Model (docs/ARCHITECTURE.md)

• 🤝 Contributing & Roadmap (CONTRIBUTING.md)

📄 License

Released under the MIT License.