# Helmdeck MCP server

> A self-hosted, containerized platform that provides AI agents with capability packs for browser automation, desktop actions, and code editing.

- Repository: https://github.com/tosin2013/helmdeck
- Page: https://hostedmcp.org/servers/tosin2013/helmdeck
- Transport: stdio
- Stars: 6
- License: Apache-2.0
- Latest version: 0.29.10

## Install

### Claude Code

```sh
claude mcp add --env 'HELMDECK_TOKEN=<YOUR_HELMDECK_TOKEN>' --env 'HELMDECK_URL=<HELMDECK_URL>' helmdeck -- npx -y @helmdeck/mcp-bridge
```

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

```json
{
  "mcpServers": {
    "helmdeck": {
      "command": "npx",
      "args": [
        "-y",
        "@helmdeck/mcp-bridge"
      ],
      "env": {
        "HELMDECK_TOKEN": "<YOUR_HELMDECK_TOKEN>",
        "HELMDECK_URL": "<HELMDECK_URL>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "helmdeck": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@helmdeck/mcp-bridge"
      ],
      "env": {
        "HELMDECK_TOKEN": "<YOUR_HELMDECK_TOKEN>",
        "HELMDECK_URL": "<HELMDECK_URL>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"helmdeck","type":"stdio","command":"npx","args":["-y","@helmdeck/mcp-bridge"],"env":{"HELMDECK_TOKEN":"<YOUR_HELMDECK_TOKEN>","HELMDECK_URL":"<HELMDECK_URL>"}}'
```

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

```json
{
  "mcpServers": {
    "helmdeck": {
      "command": "npx",
      "args": [
        "-y",
        "@helmdeck/mcp-bridge"
      ],
      "env": {
        "HELMDECK_TOKEN": "<YOUR_HELMDECK_TOKEN>",
        "HELMDECK_URL": "<HELMDECK_URL>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add helmdeck --env 'HELMDECK_TOKEN=<YOUR_HELMDECK_TOKEN>' --env 'HELMDECK_TOKEN=<YOUR_HELMDECK_TOKEN>' --env 'HELMDECK_URL=<HELMDECK_URL>' --env 'HELMDECK_URL=<HELMDECK_URL>' -- npx -y @helmdeck/mcp-bridge
```

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

```toml
[mcp_servers.helmdeck]
command = "npx"
args = ["-y", "@helmdeck/mcp-bridge"]

[mcp_servers.helmdeck.env]
HELMDECK_TOKEN = "<YOUR_HELMDECK_TOKEN>"
HELMDECK_URL = "<HELMDECK_URL>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'HELMDECK_TOKEN=<YOUR_HELMDECK_TOKEN>' -e 'HELMDECK_TOKEN=<YOUR_HELMDECK_TOKEN>' -e 'HELMDECK_URL=<HELMDECK_URL>' -e 'HELMDECK_URL=<HELMDECK_URL>' helmdeck npx -- -y @helmdeck/mcp-bridge
```

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

```json
{
  "mcpServers": {
    "helmdeck": {
      "command": "npx",
      "args": [
        "-y",
        "@helmdeck/mcp-bridge"
      ],
      "env": {
        "HELMDECK_TOKEN": "<YOUR_HELMDECK_TOKEN>",
        "HELMDECK_URL": "<HELMDECK_URL>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `HELMDECK_TOKEN` | yes | yes | JWT bearer token minted from your helmdeck control plane. Generate with: curl -X POST $HELMDECK_URL/api/v1/auth/login -d '{"username":"admin","password":"..."}' |
| `HELMDECK_TOKEN` | yes | yes | JWT bearer token minted from your helmdeck control plane |
| `HELMDECK_URL` | yes | no | Base URL of your helmdeck control plane (e.g. http://localhost:3000 for a local Compose install, or your reverse-proxied https URL) |
| `HELMDECK_URL` | yes | no | Base URL of your helmdeck control plane reachable from the container network (e.g. http://host.docker.internal:3000) |
| `HELMDECK_ADMIN_PASSWORD` | no | no |  |
| `HELMDECK_JWT_SECRET` | no | no |  |
| `HELMDECK_VAULT_KEY` | no | no |  |

## FAQ

### What makes Helmdeck different from frontier-model approaches?

Helmdeck is designed for local 7B–30B models and air-gapped environments, using capability packs to hide complex workflows behind single JSON calls, making small models as reliable as frontier models.

### Can agents see my credentials when using Helmdeck?

No, Helmdeck uses a credential vault with AES-256-GCM and placeholder-token injection so that agents never see the actual secrets.

### Does Helmdeck support Kubernetes?

Yes, Helmdeck offers a dual-tier deployment including a Helm chart for Kubernetes production environments.
