# Hatchbox MCP server

> Manage Hatchbox Rails hosting from an AI client: inspect environment variables via SSH, set or delete env vars, trigger deploys, and check deployment status.

- Repository: https://github.com/pulsemcp/mcp-servers
- Page: https://hostedmcp.org/servers/pulsemcp/hatchbox
- Official: yes
- Transport: stdio
- Stars: 81
- License: MIT
- Latest version: 0.1.3

## Install

### Claude Code

```sh
claude mcp add --env 'HATCHBOX_API_KEY=<YOUR_HATCHBOX_API_KEY>' --env 'HATCHBOX_DEPLOY_KEY=<YOUR_HATCHBOX_DEPLOY_KEY>' --env 'HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID>' --env 'HATCHBOX_APP_ID=<HATCHBOX_APP_ID>' hatchbox -- npx -y hatchbox-mcp-server
```

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

```json
{
  "mcpServers": {
    "hatchbox": {
      "command": "npx",
      "args": [
        "-y",
        "hatchbox-mcp-server"
      ],
      "env": {
        "HATCHBOX_API_KEY": "<YOUR_HATCHBOX_API_KEY>",
        "HATCHBOX_DEPLOY_KEY": "<YOUR_HATCHBOX_DEPLOY_KEY>",
        "HATCHBOX_ACCOUNT_ID": "<HATCHBOX_ACCOUNT_ID>",
        "HATCHBOX_APP_ID": "<HATCHBOX_APP_ID>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "hatchbox": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "hatchbox-mcp-server"
      ],
      "env": {
        "HATCHBOX_API_KEY": "<YOUR_HATCHBOX_API_KEY>",
        "HATCHBOX_DEPLOY_KEY": "<YOUR_HATCHBOX_DEPLOY_KEY>",
        "HATCHBOX_ACCOUNT_ID": "<HATCHBOX_ACCOUNT_ID>",
        "HATCHBOX_APP_ID": "<HATCHBOX_APP_ID>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"hatchbox","type":"stdio","command":"npx","args":["-y","hatchbox-mcp-server"],"env":{"HATCHBOX_API_KEY":"<YOUR_HATCHBOX_API_KEY>","HATCHBOX_DEPLOY_KEY":"<YOUR_HATCHBOX_DEPLOY_KEY>","HATCHBOX_ACCOUNT_ID":"<HATCHBOX_ACCOUNT_ID>","HATCHBOX_APP_ID":"<HATCHBOX_APP_ID>"}}'
```

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

```json
{
  "mcpServers": {
    "hatchbox": {
      "command": "npx",
      "args": [
        "-y",
        "hatchbox-mcp-server"
      ],
      "env": {
        "HATCHBOX_API_KEY": "<YOUR_HATCHBOX_API_KEY>",
        "HATCHBOX_DEPLOY_KEY": "<YOUR_HATCHBOX_DEPLOY_KEY>",
        "HATCHBOX_ACCOUNT_ID": "<HATCHBOX_ACCOUNT_ID>",
        "HATCHBOX_APP_ID": "<HATCHBOX_APP_ID>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add hatchbox --env 'HATCHBOX_API_KEY=<YOUR_HATCHBOX_API_KEY>' --env 'HATCHBOX_DEPLOY_KEY=<YOUR_HATCHBOX_DEPLOY_KEY>' --env 'HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID>' --env 'HATCHBOX_APP_ID=<HATCHBOX_APP_ID>' -- npx -y hatchbox-mcp-server
```

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

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

[mcp_servers.hatchbox.env]
HATCHBOX_API_KEY = "<YOUR_HATCHBOX_API_KEY>"
HATCHBOX_DEPLOY_KEY = "<YOUR_HATCHBOX_DEPLOY_KEY>"
HATCHBOX_ACCOUNT_ID = "<HATCHBOX_ACCOUNT_ID>"
HATCHBOX_APP_ID = "<HATCHBOX_APP_ID>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'HATCHBOX_API_KEY=<YOUR_HATCHBOX_API_KEY>' -e 'HATCHBOX_DEPLOY_KEY=<YOUR_HATCHBOX_DEPLOY_KEY>' -e 'HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID>' -e 'HATCHBOX_APP_ID=<HATCHBOX_APP_ID>' hatchbox npx -- -y hatchbox-mcp-server
```

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

```json
{
  "mcpServers": {
    "hatchbox": {
      "command": "npx",
      "args": [
        "-y",
        "hatchbox-mcp-server"
      ],
      "env": {
        "HATCHBOX_API_KEY": "<YOUR_HATCHBOX_API_KEY>",
        "HATCHBOX_DEPLOY_KEY": "<YOUR_HATCHBOX_DEPLOY_KEY>",
        "HATCHBOX_ACCOUNT_ID": "<HATCHBOX_ACCOUNT_ID>",
        "HATCHBOX_APP_ID": "<HATCHBOX_APP_ID>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `HATCHBOX_API_KEY` | yes | yes | API key for authentication with Hatchbox. |
| `HATCHBOX_DEPLOY_KEY` | yes | yes | Deployment webhook key for triggering deployments. |
| `HATCHBOX_ACCOUNT_ID` | yes | no | Hatchbox account ID visible in the dashboard URL. |
| `HATCHBOX_APP_ID` | yes | no | Hatchbox application ID visible in the dashboard URL. |
| `ALLOW_DEPLOYS` | no | no | Set to false to disable deployment operations. |
| `HATCHBOX_APP_NAME` | no | no | App name to filter processes if multiple apps run on the same server. |
| `READONLY` | no | no | Set to false to enable write operations for environment variables. |
| `SSH_KEY_PATH` | no | no | Path to SSH private key for server access. |
| `WEB_SERVER_IP_ADDRESS` | no | no | IP address of Hatchbox server for SSH access to read environment variables. |

## Tools (5)

- `name`
- `value`
- `names`
- `sha`
- `activityId`

## FAQ

### What environment variables does the Hatchbox MCP server need?

It requires HATCHBOX_API_KEY, HATCHBOX_ACCOUNT_ID, HATCHBOX_APP_ID, and HATCHBOX_DEPLOY_KEY. Optional SSH variables like WEB_SERVER_IP_ADDRESS and SSH_KEY_PATH enable reading env vars.

### How do I read environment variables from my Hatchbox server?

Configure WEB_SERVER_IP_ADDRESS and set up SSH key access to the deploy user so the getEnvVars and getEnvVar tools are enabled.

### Is the Hatchbox MCP server read-only by default?

Yes, read-only mode is enabled by default and prevents modifications to your environment. Set READONLY to false to allow setting or deleting env vars.

### Can I disable deployments through the Hatchbox MCP server?

Yes, set ALLOW_DEPLOYS to false to turn off deploy operations, which is recommended for production.

### How do I handle multiple Rails apps on one Hatchbox server?

Set HATCHBOX_APP_NAME to the app name shown in your dashboard so the MCP server filters the process list to the correct puma process.
