The DeployHQ MCP Server is a Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop and Claude Code to interact with your DeployHQ deployments. This allows you to manage deployments, check status, view logs, and more using natural language.

## What is MCP?

The Model Context Protocol (MCP) is a standard protocol that allows AI assistants to interact with external tools and services. The DeployHQ MCP Server implements this protocol to provide seamless integration between AI assistants and your DeployHQ account.

## Features

- **Full DeployHQ Integration**: Access projects, servers, and deployments through AI
- **Easy Installation**: Use directly with npx - no installation required
- **Secure**: Credentials via environment variables, never stored
- **Works with Claude Desktop and Claude Code**: Compatible with both MCP clients

## Available Tools

The MCP server provides 18 tools that AI assistants can use:

### list_projects
List all projects in your DeployHQ account.

**Returns**: Array of projects with repository information and deployment status.

### get_project
Get detailed information about a specific project.

**Parameters**:
- `permalink` (string): Project permalink or identifier

### list_servers
List all servers configured for a project.

**Parameters**:
- `project` (string): Project permalink

### list_deployments
List deployments for a project with pagination support.

**Parameters**:
- `project` (string): Project permalink
- `page` (number, optional): Page number for pagination
- `server_uuid` (string, optional): Filter by server UUID

### get_deployment
Get detailed information about a specific deployment.

**Parameters**:
- `project` (string): Project permalink
- `uuid` (string): Deployment UUID

### get_deployment_log
Get the deployment log for a specific deployment. Useful for debugging failed deployments.

**Parameters**:
- `project` (string): Project permalink
- `uuid` (string): Deployment UUID

**Returns**: Complete deployment log as text

### create_deployment
Create a new deployment for a project.

**Parameters**:
- `project` (string): Project permalink
- `parent_identifier` (string): Server or server group UUID
- `start_revision` (string): Starting commit hash
- `end_revision` (string): Ending commit hash
- `branch` (string, optional): Branch to deploy from
- `mode` (string, optional): "queue" or "preview"
- `copy_config_files` (boolean, optional): Copy config files
- `run_build_commands` (boolean, optional): Run build commands
- `use_build_cache` (boolean, optional): Use build cache
- `use_latest` (string, optional): Use latest deployed commit as start

### list_ssh_keys
List all SSH public keys for the account. Use these keys to authorize DeployHQ on servers for SSH-based deployments.

**Returns**: Array of SSH keys with identifier, title, public key, key type, and fingerprint. Never returns private keys.

### create_ssh_key
Create a new SSH key pair for the account.

**Parameters**:
- `title` (string): Title for the SSH key
- `key_type` (string, optional): Key type — ED25519 (default) or RSA

### list_global_environment_variables
List all global (account-level) environment variables.

**Returns**: Array of environment variables with name, masked value, lock status, and build pipeline setting.

### create_global_environment_variable
Create a new global environment variable.

**Parameters**:
- `name` (string): Variable name (must start with a letter, only letters/numbers/underscores)
- `value` (string): Variable value (encrypted at rest)
- `locked` (boolean, optional): Lock the variable to prevent changes
- `build_pipeline` (boolean, optional): Make available in build pipeline

### update_global_environment_variable
Update an existing global environment variable.

**Parameters**:
- `id` (string): Variable identifier
- `name` (string, optional): New variable name
- `value` (string, optional): New variable value
- `locked` (boolean, optional): Lock the variable
- `build_pipeline` (boolean, optional): Build pipeline availability

### delete_global_environment_variable
Delete a global environment variable.

**Parameters**:
- `id` (string): Variable identifier

### list_global_config_files
List all global (account-level) config file templates.

**Returns**: Array of config files with paths, descriptions, and build pipeline settings.

### get_global_config_file
Get a specific global config file template including its full body content.

**Parameters**:
- `id` (string): Config file identifier (UUID)

### create_global_config_file
Create a new global config file template. These templates can be copied to projects from the account settings.

**Parameters**:
- `path` (string): File path (e.g. config/database.yml)
- `body` (string): File contents
- `description` (string, optional): Description of the config file
- `build` (boolean, optional): Use with the build pipeline

### update_global_config_file
Update an existing global config file template.

**Parameters**:
- `id` (string): Config file identifier (UUID)
- `path` (string, optional): File path
- `body` (string, optional): File contents
- `description` (string, optional): Description
- `build` (boolean, optional): Build pipeline flag

### delete_global_config_file
Delete a global config file template. This action is irreversible.

**Parameters**:
- `id` (string): Config file identifier (UUID)

## Installation and Configuration

### Prerequisites

- Node.js 18 or higher
- DeployHQ account with API access
- Claude Desktop or Claude Code installed

### Getting Your Credentials

You'll need three pieces of information:

1. **Email**: Your DeployHQ login email
2. **API Key**: Found in Settings > Security in your DeployHQ account
3. **Account Name**: Your account name from the URL (https://ACCOUNT.deployhq.com)

### Configuration for Claude Desktop

Edit your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the following configuration:

```json
{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}
```

After adding the configuration, restart Claude Desktop.

### Configuration for Claude Code

Add the configuration to your `.claude.json` file in your project directory:

```json
{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}
```

### Optional Configuration

You can add an optional `LOG_LEVEL` environment variable to control logging verbosity:

```json
{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account-name",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

Available log levels:
- **ERROR**: Only show errors
- **INFO**: Show info and errors (default)
- **DEBUG**: Show all logs including detailed API calls

## Usage Examples

Once configured, you can interact with DeployHQ using natural language. Here are some common examples:

### Check Deployment Status

```
You: What's the status of my latest deployment for my-app?
```

The AI will use the `list_deployments` and `get_deployment` tools to show you the current deployment status.

### List Your Projects

```
You: List all my DeployHQ projects
```

The AI will use the `list_projects` tool to show all your projects with their current status.

### View Server Configuration

```
You: Show me the servers configured for my-app
```

The AI will use the `list_servers` tool to display all servers for the specified project.

### Debug Failed Deployment

```
You: Why did the last deployment fail for my-app?
```

The AI will use `list_deployments` to find the failed deployment, then `get_deployment_log` to retrieve and analyze the deployment log.

### Create a New Deployment

```
You: Deploy the latest changes to production for my-app
```

The AI will:
1. Use `list_projects` to find your project
2. Use `list_servers` to find the production server
3. Use `list_deployments` to get the last deployed revision
4. Use `create_deployment` to queue the deployment
5. Use `get_deployment` to show the deployment status

### Get SSH Keys for Server Setup

```
You: Show me my account's SSH public keys
```

The AI will use the `list_ssh_keys` tool to display all SSH keys, which you can then use to authorize DeployHQ on your servers.

### Manage Global Environment Variables

```
You: List all global environment variables
```

The AI will use the `list_global_environment_variables` tool to show all account-level variables.

```
You: Create a global environment variable called DATABASE_URL with value postgres://localhost/mydb
```

The AI will use the `create_global_environment_variable` tool to create the variable, which will then be available to all projects.

### Manage Global Config Files

```text
You: List all global config file templates
```

The AI will use the `list_global_config_files` tool to show all account-level config file templates.

```text
You: Create a global config file template for config/database.yml with production database settings
```

The AI will use the `create_global_config_file` tool to create the template, which can then be copied to projects from the account settings.

### Monitor Deployment Progress

```
You: Show me the deployment log for the current deployment of my-app
```

The AI will use `list_deployments` to find the active deployment and `get_deployment_log` to show you the real-time progress.

## Troubleshooting

### Server Won't Start

**Problem**: Server exits immediately after starting

**Solutions**:
- Check that all required environment variables are set correctly
- Verify Node.js version is 18 or higher: `node --version`
- Check Claude Desktop/Code logs for error messages
- Try setting `LOG_LEVEL=DEBUG` for more details

**Log locations**:
- **macOS**: `~/Library/Logs/Claude/`
- **Windows**: `%APPDATA%\Claude\logs\`

### Authentication Errors

**Problem**: "Authentication failed" or 401/403 errors

**Solutions**:
- Verify your email and API key are correct
- Check that your API key is active in Settings > Security
- Ensure your account has API access enabled
- Try logging into DeployHQ web interface with the same credentials

### Project Not Found

**Problem**: "Project not found" or 404 errors

**Solutions**:
- Use the `list_projects` tool to see the exact permalink format
- Project permalinks are case-sensitive
- Verify you have access to the project in DeployHQ

### Deployment Fails

**Problem**: Deployment created but fails immediately

**Solutions**:
- Use `get_deployment_log` to see detailed error messages
- Verify the server UUID is correct with `list_servers`
- Check that start and end revisions exist in your repository
- Ensure the server has correct deploy keys configured in DeployHQ

### Connection Timeouts

**Problem**: "Request timeout" errors

**Solutions**:
- Check your internet connection
- Verify DeployHQ is accessible: `curl https://your-account.deployhq.com`
- Large deployment lists may take time - the tool supports pagination
- Try again in a moment if DeployHQ is experiencing issues

## Frequently Asked Questions

### What is the difference between the MCP Server and the API?

The MCP Server is designed for AI assistants to interact with DeployHQ using natural language, while the API is for direct programmatic access. The MCP Server uses the DeployHQ API under the hood, but provides a conversational interface through AI assistants.

### Do I need to install anything besides npx?

No. The `npx` command will automatically download and run the latest version of the MCP server. You just need Node.js 18 or higher installed on your system.

### Can I use the MCP Server with multiple DeployHQ accounts?

Yes. You can configure multiple MCP servers in your configuration file, each with different credentials. Simply use different names for each server configuration (e.g., "deployhq-production", "deployhq-staging").

Example:
```json
{
  "mcpServers": {
    "deployhq-production": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "prod@example.com",
        "DEPLOYHQ_API_KEY": "prod-key",
        "DEPLOYHQ_ACCOUNT": "production-account"
      }
    },
    "deployhq-staging": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "staging@example.com",
        "DEPLOYHQ_API_KEY": "staging-key",
        "DEPLOYHQ_ACCOUNT": "staging-account"
      }
    }
  }
}
```

### Is my API key stored anywhere?

No. Your credentials are passed as environment variables to the MCP server process and are never written to disk or sent anywhere except directly to the DeployHQ API over HTTPS.

### Can the AI assistant trigger deployments without asking me?

The AI assistant will typically ask for confirmation before creating a deployment. However, the exact behavior depends on how you phrase your request. For safety, always review what the AI plans to do before confirming.

### What permissions does the API key need?

The API key should have the same permissions as your DeployHQ user account. To create deployments, your account needs deployment permissions for the relevant projects. To view deployment logs, you need read access to the projects.

### Does the MCP Server work offline?

No. The MCP Server requires an internet connection to communicate with the DeployHQ API. All operations are performed in real-time against your DeployHQ account.

### How do I update to the latest version?

Since the MCP Server is run via `npx` with the `-y` flag, it automatically uses the latest published version from npm. To force a fresh download, you can clear the npx cache:

```bash
npx clear-npx-cache
```

Or specify a specific version:

```json
{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server@1.0.0"]
    }
  }
}
```

### Can I use this with other AI assistants besides Claude?

The MCP Server implements the standard Model Context Protocol, so it should work with any MCP-compatible AI assistant. However, it has been primarily tested with Claude Desktop and Claude Code.

### What happens if I have a slow internet connection?

The MCP Server includes timeout handling, but operations may be slower on slow connections. For large deployment lists, consider using pagination by asking the AI to show results in smaller batches.

### Can I see what API calls are being made?

Yes. Set the `LOG_LEVEL` environment variable to `DEBUG` in your configuration. This will output detailed information about all API calls, including URLs and response data, to the Claude Desktop/Code logs.

### How do I find my project permalink?

You can ask the AI to "list all my DeployHQ projects" and it will show you the permalinks for all your projects. Alternatively, the permalink is visible in the URL when you view a project in the DeployHQ web interface: `https://your-account.deployhq.com/projects/YOUR-PERMALINK`

### Can I deploy to multiple servers at once?

Yes. You can create server groups in DeployHQ and use the group UUID as the `parent_identifier` when creating a deployment. Ask the AI to "show me the servers for my-app" to see both individual servers and server groups.

### What should I do if the AI doesn't understand my request?

Try being more specific with project names and actions. For example, instead of "deploy my app", try "create a deployment for my-app project to the production server with the latest changes". You can also ask the AI to "list my projects" first to get the exact project names.

## Security

- **Environment Variables**: Credentials are passed via environment variables and never stored
- **Local Execution**: When using npx, credentials stay local to your machine
- **No Telemetry**: No data is sent anywhere except directly to DeployHQ API
- **HTTPS Only**: All API communication uses HTTPS

## Additional Resources

- **npm Package**: https://www.npmjs.com/package/deployhq-mcp-server
- **GitHub Repository**: https://github.com/deployhq/deployhq-mcp-server
- **DeployHQ API Documentation**: https://www.deployhq.com/support/api
- **Model Context Protocol**: https://modelcontextprotocol.io
- **Report Issues**: https://github.com/deployhq/deployhq-mcp-server/issues

## Related Tools

- [The DeployHQ API](https://www.deployhq.com/support/api) - Direct REST API access
- [The DeployHQ CLI](https://www.deployhq.com/support/cli) - Command line tool for deployments