Manage Hatchbox Rails hosting from an AI client: inspect environment variables via SSH, set or delete env vars, trigger deploys, and check deployment status.
Also known as pulsemcp/mcp-servers, hatchbox-mcp-server
- Stars
- 81
- Tools
- 5
- Downloads, 30 days
- 205
- Latest version
- 0.1.3
- Last commit
- Oct 9, 2026
- License
- MIT
What is Hatchbox MCP?
Hatchbox manages Hatchbox Rails hosting from an AI client: inspect environment variables via SSH, set or delete env vars, trigger deploys, and check deployment status. It exposes 5 tools, such as name, value, names.
Summary generated from the project's README
About Hatchbox MCP server
Managing Rails applications on Hatchbox hosting becomes possible directly through an AI assistant using this MCP server. Developers can oversee their hosting environment by interacting with the Hatchbox API to control deployments and manage configuration settings without leaving their chat interface.
Users connect the server by providing a Hatchbox API key, account ID, application ID, and deployment webhook key. For advanced tasks like inspecting environment variables via SSH, you must also configure a server IP address and an SSH private key path. The server includes built-in security controls, such as a read-only mode that is enabled by default to prevent accidental changes to production environments.
Specific tools allow for granular control, including triggerDeploy to start new code releases and checkDeploy to monitor their progress. You can also use getEnvVars to view all environment variables or setEnvVar to update specific values if you disable the read-only restriction. This setup is ideal for developers who want to automate deployment workflows and environment configuration through natural language commands.
What you can do with it
- 1Monitor deployment progressAsk the AI to check if a recent code deployment has finished successfully.
- 2Inspect application configurationRetrieve all environment variables from your server using SSH access.
- 3Update environment settingsChange a specific environment variable value to update your application behavior.
- 4Deploy specific code versionsInstruct the assistant to deploy a particular commit SHA to your hosting environment.
Written from the project's README. Every use case is checked against a quote from it.
How to install Hatchbox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Hatchbox MCP in Claude Code
$ 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-serverInstall Hatchbox MCP in Cursor
~/.cursor/mcp.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>"
}
}
}
}Install Hatchbox MCP in VS Code
.vscode/mcp.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>"
}
}
}
}Install Hatchbox MCP in VS Code CLI
$ 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>"}}'Install Hatchbox MCP in Claude Desktop
claude_desktop_config.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>"
}
}
}
}Install Hatchbox MCP in Codex
$ 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-serverInstall Hatchbox MCP in Codex config.toml
~/.codex/config.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>"
Install Hatchbox MCP in Gemini CLI
$ 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-serverInstall Hatchbox MCP in Gemini settings.json
~/.gemini/settings.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>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Hatchbox MCP tools 5
Detected from the READMEnamevaluenamesshaactivityId
Configuration
HATCHBOX_API_KEYRequiredSecretAPI key for authentication with Hatchbox.
HATCHBOX_DEPLOY_KEYRequiredSecretDeployment webhook key for triggering deployments.
HATCHBOX_ACCOUNT_IDRequiredHatchbox account ID visible in the dashboard URL.
HATCHBOX_APP_IDRequiredHatchbox application ID visible in the dashboard URL.
ALLOW_DEPLOYSSet to false to disable deployment operations.
HATCHBOX_APP_NAMEApp name to filter processes if multiple apps run on the same server.
READONLYSet to false to enable write operations for environment variables.
SSH_KEY_PATHPath to SSH private key for server access.
WEB_SERVER_IP_ADDRESSIP address of Hatchbox server for SSH access to read environment variables.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubHatchbox MCP Server
An MCP server for Hatchbox - Rails hosting made simple for small businesses.
Overview
This MCP server provides tools to interact with Hatchbox's API, allowing you to manage environment variables and deployments for your Rails applications directly from your AI assistant.
Key Features
- Environment Variable Management:
- View all environment variables (via SSH)
- Get specific environment variables (via SSH)
- Set and update environment variables
- Delete environment variables
- Deployment Control: Trigger deployments and check their status
- Security Features:
- Read-only mode by default
- Configurable deployment permissions
- SSH-based secure access for reading env vars
- Secure Authentication: Uses API keys and SSH keys for secure access
Installation
npm install hatchbox-mcp-server
Configuration
Environment Variables
Required Variables
HATCHBOX_API_KEY: Your Hatchbox API key for authenticationHATCHBOX_ACCOUNT_ID: Your Hatchbox account IDHATCHBOX_APP_ID: Your Hatchbox application IDHATCHBOX_DEPLOY_KEY: Your deployment webhook key
Optional Variables for SSH Access
WEB_SERVER_IP_ADDRESS: IP address of your Hatchbox server (enables getEnvVars and getEnvVar tools)SSH_KEY_PATH: Path to SSH private key (defaults to ~/.ssh/id_rsa)HATCHBOX_APP_NAME: App name to filter processes if multiple apps on server (see example below)
Security Configuration
READONLY: Set tofalseto enable write operations (default:true)ALLOW_DEPLOYS: Set tofalseto disable deployment operations (default:true)
You can find these values in your Hatchbox dashboard:
- API key: Account settings
- Account ID: Visible in the URL when viewing your account
- App ID: Visible in the URL when viewing your application
- Deploy key: Application deployment settings
- Server IP: Your server's public IP address (for SSH access)
SSH Setup (Optional - for reading env vars)
To enable the getEnvVars and getEnvVar tools, you need SSH access to your Hatchbox server:
-
Add your SSH public key to the deploy user on your Hatchbox server:
ssh-copy-id deploy@your-server-ip -
Test SSH access:
ssh deploy@your-server-ip "echo 'SSH access working'" -
Configure the MCP server with your server's IP address (see configuration below)
Multiple Apps on Same Server
If you have multiple Rails applications running on the same Hatchbox server, you'll need to specify the HATCHBOX_APP_NAME to identify which app's environment variables to read:
# Example: If your server has multiple apps running
# App 1: mystore (running on port 3000)
# App 2: blog (running on port 3001)
# App 3: api (running on port 3002)
# To read env vars for the 'mystore' app:
HATCHBOX_APP_NAME=mystore
# To read env vars for the 'blog' app:
HATCHBOX_APP_NAME=blog
The app name should match the name shown in your Hatchbox dashboard. This filters the process list to find the correct puma process for your specific application.
Claude Desktop Configuration
Add the server to your Claude Desktop configuration file:
macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hatchbox": {
"command": "npx",
"args": ["-y", "hatchbox-mcp-server"],
"env": {
"HATCHBOX_API_KEY": "your-api-key-here",
"HATCHBOX_ACCOUNT_ID": "1852",
"HATCHBOX_APP_ID": "8540",
"HATCHBOX_DEPLOY_KEY": "your-deploy-key-here",
"// Optional - for SSH access to read env vars": "",
"WEB_SERVER_IP_ADDRESS": "165.232.133.75",
"SSH_KEY_PATH": "/Users/yourname/.ssh/id_rsa",
"HATCHBOX_APP_NAME": "myapp",
"// Optional - security settings": "",
"READONLY": "false",
"ALLOW_DEPLOYS": "true"
}
}
}
}
Tools
Environment Variables
getEnvVars
Get all environment variables from the Hatchbox server via SSH.
Requirements: WEB_SERVER_IP_ADDRESS must be configured.
Parameters: None
Example:
"Show me all environment variables"
getEnvVar
Get a specific environment variable from the Hatchbox server via SSH.
Requirements: WEB_SERVER_IP_ADDRESS must be configured.
Parameters:
name(string, required): The name of the environment variable to retrieve
Example:
{
"name": "RAILS_ENV"
}
setEnvVar
Set or update an environment variable.
Requirements: READONLY must be set to false.
Parameters:
name(string, required): The environment variable namevalue(string, required): The environment variable value
Example:
{
"name": "DATABASE_URL",
"value": "postgres://user:pass@host:5432/dbname"
}
deleteEnvVars
Delete one or more environment variables.
Requirements: READONLY must be set to false.
Parameters:
names(array of strings, required): Array of environment variable names to delete
Example:
{
"names": ["OLD_VAR", "UNUSED_VAR"]
}
Deployments
triggerDeploy
Trigger a new deployment for your application.
Requirements: ALLOW_DEPLOYS must be set to true (default).
Parameters:
sha(string, optional): Specific commit SHA to deploy (latest if not provided)
Example:
{
"sha": "abc123def456"
}
checkDeploy
Check the status of a deployment.
Requirements: ALLOW_DEPLOYS must be set to true (default).
Parameters:
activityId(string, required): The deployment activity ID returned from triggerDeploy
Example:
{
"activityId": "12345"
}
Usage Examples
Here are some example queries you can use with Claude:
Reading Environment Variables (requires WEB_SERVER_IP_ADDRESS)
-
View all environment variables: "Show me all environment variables"
-
Get a specific variable: "What is the value of RAILS_ENV?"
Writing Environment Variables (requires READONLY=false)
-
Set an environment variable: "Set the RAILS_ENV to production"
-
Delete environment variables: "Delete the OLD_VAR and UNUSED_VAR environment variables"
Deployments (requires ALLOW_DEPLOYS=true)
-
Deploy the latest code: "Deploy the latest commit to Hatchbox"
-
Deploy a specific commit: "Deploy commit abc123def456 to Hatchbox"
-
Check deployment status: "Check the status of deployment activity 12345"
Security Notes
API Security
- Store your API keys securely and never commit them to version control
- The server only has access to the Hatchbox accounts and applications that your API key can access
SSH Security
- SSH access exposes ALL environment variables including secrets
- Ensure your SSH key is properly secured
- Consider using a dedicated read-only SSH key if possible
- Only configure WEB_SERVER_IP_ADDRESS if you trust the MCP client with your secrets
Permission Modes
- Read-only mode (default): Prevents accidental modifications to your production environment
- Deployment control: Can be disabled separately from write operations
- Configure permissions based on your security requirements:
- Development:
READONLY=false,ALLOW_DEPLOYS=true - Staging:
READONLY=false,ALLOW_DEPLOYS=true - Production:
READONLY=true,ALLOW_DEPLOYS=false(recommended)
- Development:
- All API communications are encrypted using HTTPS
Development
This server is part of the PulseMCP organization's collection of MCP servers. For development instructions and contribution guidelines, see the main repository.
License
This project is licensed under the MIT License.
Hatchbox MCP questions
How do I add Hatchbox MCP to Claude Code?
Run 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 in your terminal. Add --scope user to make it available in every project.
How do I add Hatchbox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Hatchbox MCP provide?
It exposes 5 tools, including name, value, names, sha, activityId.
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.