# BasicDeploy MCP server

> Lets AI agents deploy and manage containers with integrated PostgreSQL, S3 storage, and Kafka brokers via a single MCP call.

- Repository: https://github.com/AkaciaNL/basicdeploy-mcp
- Page: https://hostedmcp.org/servers/akacianl/basicdeploy-mcp
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 1.0.7

## Install

### Claude Code

```sh
claude mcp add --env 'BASICDEPLOY_API_KEY=<YOUR_BASICDEPLOY_API_KEY>' basicdeploy-mcp -- npx -y basicdeploy-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "basicdeploy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "basicdeploy-mcp"
      ],
      "env": {
        "BASICDEPLOY_API_KEY": "<YOUR_BASICDEPLOY_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "basicdeploy-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "basicdeploy-mcp"
      ],
      "env": {
        "BASICDEPLOY_API_KEY": "<YOUR_BASICDEPLOY_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"basicdeploy-mcp","type":"stdio","command":"npx","args":["-y","basicdeploy-mcp"],"env":{"BASICDEPLOY_API_KEY":"<YOUR_BASICDEPLOY_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "basicdeploy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "basicdeploy-mcp"
      ],
      "env": {
        "BASICDEPLOY_API_KEY": "<YOUR_BASICDEPLOY_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add basicdeploy-mcp --env 'BASICDEPLOY_API_KEY=<YOUR_BASICDEPLOY_API_KEY>' -- npx -y basicdeploy-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.basicdeploy-mcp]
command = "npx"
args = ["-y", "basicdeploy-mcp"]

[mcp_servers.basicdeploy-mcp.env]
BASICDEPLOY_API_KEY = "<YOUR_BASICDEPLOY_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'BASICDEPLOY_API_KEY=<YOUR_BASICDEPLOY_API_KEY>' basicdeploy-mcp npx -- -y basicdeploy-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "basicdeploy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "basicdeploy-mcp"
      ],
      "env": {
        "BASICDEPLOY_API_KEY": "<YOUR_BASICDEPLOY_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BASICDEPLOY_API_KEY` | yes | yes | Your BasicDeploy API key (bd_...). Create one at https://basicdeploy.com/api-keys — required to call any tool (the server still starts without it so clients can introspect the tool list). |
| `BASICDEPLOY_URL` | no | no | BasicDeploy API base URL. |

## Tools (12)

- `list_containers`: List all BasicDeploy containers owned by (or shared with) the authenticated user. Returns each container's id, subdomain, public URL, status, and creation time.
- `create_container`: Create a new empty BasicDeploy container. A PostgreSQL database and an S3 bucket are provisioned automatically for it. Returns the container's id, subdomain, and public URL. Use deploy_app or exec_command afterwards to put an application in it. Optional memoryMb (256/512/1024/2048) and alwaysOn require the plan/add-ons to allow them (see get_account); larger sizes need Pro/Scale, and always-on on Free consumes a paid add-on slot.
- `set_always_on`: Turn a container's always-on (24/7, never sleeps) flag on or off. On Free this consumes a paid always-on add-on slot (fails if none is free); on Pro/Scale every container is always-on already. Returns the updated container.
- `wake_container`: Wake a slept container so it serves traffic again (start it). A no-op if it is already running. Note: any web request to the container's public URL also wakes it automatically. Returns the updated container.
- `sleep_container`: Sleep a running container: stop it to free memory while keeping its volume, database, and public URL, so it wakes again on the next request. Returns the updated container.
- `get_account`: Show the account's plan and capabilities: plan tier, container limit (plan base + add-ons), the memory sizes you may select, storage limit, how many always-on add-ons you hold, and whether containers auto-sleep. Use this to see what you're allowed to set.
- `get_container`: Get full details of one container: id, subdomain, public URL, status, ports, database name and username, S3 bucket, volume path, and timestamps.
- `exec_command`: Run a shell command inside a container (like docker exec). Returns the combined stdout/stderr output and the exit code. Useful for inspecting files, installing packages, or restarting processes inside the container.
- `get_logs`: Fetch recent logs from a container. Use this to debug crashes or check application output.
- `deploy_app`: Deploy an application from a local tarball (.tar, .tar.gz, .tgz, or .zip) to BasicDeploy. The runtime (Node.js, Python, or Go) is auto-detected from the archive contents. If containerId is omitted, a new container (with DB + S3) is created for the app; if provided, the archive is deployed into that existing container. Returns the resulting container and its public URL.
- `share_container`: Share a container with another BasicDeploy user by email, giving them access to it. The recipient is emailed a link that signs them in and opens the container. Optionally pass expiresInHours to make the share expire after that many hours (omit for a share that never expires).
- `delete_container`: PERMANENTLY delete a container. This destroys the container, its database, and all its files (S3 bucket contents included) and cannot be undone. Only call this when the user has clearly asked for the container to be removed.

## FAQ

### What services are included in a BasicDeploy container?

Every container automatically includes a PostgreSQL database, S3-compatible object storage, a Kafka broker, and a public HTTPS URL.

### How do I deploy an application to a container?

You can deploy a .tar, .tar.gz, .tgz, or .zip file from your disk using the deploy_app tool, which auto-detects the runtime and starts the app on port 8080.

### What environment variables are provided to my deployed app?

The runtime presets variables for your database URL, S3 credentials, S3 bucket, and Kafka connection details.

### Can I share my container with others?

Yes, you can share a container with another user via email, and you can optionally set an expiration time for the share.
