# Deployhq Mcp Server

> DeployHQ MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-deployhq-deployhq-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [deployhq](https://agentstack.voostack.com/s/deployhq)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [deployhq](https://github.com/deployhq)
- **Source:** https://github.com/deployhq/deployhq-mcp-server
- **Website:** https://deployhq.com/

## Install

```sh
agentstack add mcp-deployhq-deployhq-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# DeployHQ MCP Server

A Model Context Protocol (MCP) server for DeployHQ that enables AI assistants like Claude Desktop and Claude Code to interact with your DeployHQ deployments.

## 🚀 Features

- **Full DeployHQ API Integration**: Access projects, servers, and deployments
- **Easy Installation**: Use directly with `npx` - no installation required
- **Works with Claude Desktop & Claude Code**: stdio transport for both MCP clients
- **Secure**: Credentials via environment variables, never stored
- **Type-Safe**: Built with TypeScript and Zod validation
- **Multiple Transports**: stdio (primary), SSE, and HTTP (optional for hosting)
- **Production-Ready**: Comprehensive error handling and logging

## 📋 Available Tools

The MCP server provides **18 tools** for AI assistants:

| Tool | Description | Parameters |
|------|-------------|------------|
| `list_projects` | List all projects | None |
| `get_project` | Get project details | `permalink` |
| `list_servers` | List project servers | `project` |
| `list_deployments` | List deployments with pagination | `project`, `page?`, `server_uuid?` |
| `get_deployment` | Get deployment details | `project`, `uuid` |
| `get_deployment_log` | Get deployment log output | `project`, `uuid` |
| `create_deployment` | Create new deployment | `project`, `parent_identifier`, `start_revision`, `end_revision`, + optional params |
| `list_ssh_keys` | List all SSH public keys | None |
| `create_ssh_key` | Create a new SSH key pair | `title`, `key_type?` |
| `list_global_environment_variables` | List all global environment variables | None |
| `create_global_environment_variable` | Create a global environment variable | `name`, `value`, `locked?`, `build_pipeline?` |
| `update_global_environment_variable` | Update a global environment variable | `id`, `name?`, `value?`, `locked?`, `build_pipeline?` |
| `delete_global_environment_variable` | Delete a global environment variable | `id` |
| `list_global_config_files` | List all global config file templates | None |
| `get_global_config_file` | Get a global config file with body | `id` |
| `create_global_config_file` | Create a global config file template | `path`, `body`, `description?`, `build?` |
| `update_global_config_file` | Update a global config file template | `id`, `path?`, `body?`, `description?`, `build?` |
| `delete_global_config_file` | Delete a global config file template | `id` |

### `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.

**Returns**: Array of SSH keys with public keys, fingerprints, and key types. 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 names, masked values, and settings.

### `create_global_environment_variable`
Create a new global environment variable available across all projects.

**Parameters**:
- `name` (string): Variable name
- `value` (string): Variable value
- `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): Environment variable identifier
- `name` (string, optional): Variable name
- `value` (string, optional): Variable value
- `locked` (boolean, optional): Lock status
- `build_pipeline` (boolean, optional): Build pipeline availability

### `delete_global_environment_variable`
Delete a global environment variable. This action is irreversible.

**Parameters**:
- `id` (string): Environment variable identifier

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

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

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

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

### `create_global_config_file`
Create a new global config file template.

**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 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)

## 🚀 Quick Start

### Easy Installation with Claude Code

The fastest way to install for Claude Code:

```bash
claude mcp add --transport stdio deployhq --env DEPLOYHQ_EMAIL=your-email@example.com --env DEPLOYHQ_API_KEY=your-api-key --env DEPLOYHQ_ACCOUNT=your-account -- npx -y deployhq-mcp-server
```

Replace `your-email@example.com`, `your-api-key`, and `your-account` with your actual DeployHQ credentials.

### Manual Configuration (Works for Both Claude Desktop and Claude Code)

The same configuration works for both clients. Copy from `docs/claude-config.json` and add your credentials.

**For Claude Desktop:**

Edit your config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Then restart Claude Desktop.

**For Claude Code:**

Add to your `.claude.json` file in your project directory, then exit and restart your Claude session (type `exit` or Ctrl+D, then run `claude`).

**Configuration:**

```json
{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
        // Optional: "LOG_LEVEL": "INFO"  (ERROR, INFO, or DEBUG)
      }
    }
  }
}
```

**Note**: Only the 3 DeployHQ credentials are required. `LOG_LEVEL` is optional and defaults to `INFO`.

### Start Using

Once configured, you can ask Claude to interact with DeployHQ:
- "List all my DeployHQ projects"
- "Show me the servers for project X"
- "Get the latest deployment status for project Y"
- "Create a new deployment for project Z"
- "Show me the deployment log for the latest deployment"
- "List my global environment variables"
- "Create a global config file template for database.yml"
- "Show my SSH keys"

## 💡 Common Usage Examples

### Check Deployment Status
```
User: What's the status of my latest deployment for my-app?
Claude: [Uses list_deployments → get_deployment → shows status]
```

### Debug Failed Deployment
```
User: Why did the last deployment fail for my-app?
Claude: [Uses list_deployments → get_deployment_log → analyzes log]
```

### Deploy Latest Changes
```
User: Deploy the latest changes to production for my-app
Claude: [Uses list_servers → list_deployments → create_deployment with use_latest]
```

### Complete Workflow Example
```
User: I want to deploy my-app to production with the latest changes

Claude will:
1. Use list_projects to find "my-app"
2. Use list_servers to find production server UUID
3. Use list_deployments with use_latest to get last revision
4. Use create_deployment to queue deployment
5. Use get_deployment to show status
6. Use get_deployment_log if anything fails
```

## 🔧 Configuration Options

### Environment Variables

#### Required
- `DEPLOYHQ_EMAIL`: Your DeployHQ login email
- `DEPLOYHQ_API_KEY`: Your DeployHQ password/API key
- `DEPLOYHQ_ACCOUNT`: Your DeployHQ account name (from URL: `https://ACCOUNT.deployhq.com`)

#### Optional
- `LOG_LEVEL`: Controls log verbosity - `ERROR`, `INFO`, or `DEBUG` (default: `INFO`)
- `NODE_ENV`: Environment mode - `production` or `development`
- `DEPLOYHQ_READ_ONLY`: Set to `true` to block all mutating operations (default: `false`)

### Log Levels

Control verbosity with the `LOG_LEVEL` environment variable:

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

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

## 🐛 Troubleshooting

### Server Won't Start

**Problem**: Server exits immediately after starting

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

### Authentication Errors

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

**Solutions**:
- Verify your email and API key are correct
- Check that your API key hasn't expired
- Ensure your account has API access enabled
- Try logging into DeployHQ web interface with same credentials

### Project Not Found

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

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

### Deployment Creation Blocked

**Problem**: "Server is running in read-only mode" error when trying to create deployments

**Solution**:
- Read-only mode is disabled by default, but you may have enabled it
- To disable read-only mode, set `DEPLOYHQ_READ_ONLY=false` in your environment variables
- Or use the `--read-only=false` CLI flag
- See the [Security](#-security) section for detailed instructions on read-only mode

### Deployment Fails

**Problem**: Deployment created but fails immediately

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

### Connection Timeouts

**Problem**: "Request timeout" errors

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

### Logs Not Showing

**Problem**: Not seeing any log output

**Solutions**:
- Logs go to stderr, not stdout (for stdio transport)
- Check Claude Desktop/Code logs location:
  - macOS: `~/Library/Logs/Claude/`
  - Windows: `%APPDATA%\Claude\logs\`
- Set `LOG_LEVEL=DEBUG` for verbose output
- For hosted mode, check Digital Ocean logs

### Getting Your DeployHQ Credentials

1. **Username**: Your DeployHQ login email
2. **Password**: Your DeployHQ password
3. **Account**: Your DeployHQ account name (visible in the URL: `https://ACCOUNT.deployhq.com`)

## 🏗️ Architecture

```
┌─────────────────┐                    ┌─────────────┐
│  Claude Desktop │    stdio/JSON-RPC  │  DeployHQ   │
│  or Claude Code │◄──────────────────►│  API        │
│                 │    (via npx)       │             │
│  Environment    │                    │             │
│  Variables ─────┼───────────────────►│ Basic Auth  │
└─────────────────┘                    └─────────────┘
```

- **Claude Desktop/Code**: MCP clients that spawn the server via `npx`
- **MCP Server**: Reads credentials from environment variables, communicates via stdio
- **DeployHQ API**: REST API with HTTP Basic Authentication

## 📦 Prerequisites

- **Node.js 18+** (Node 20+ recommended)
- **DeployHQ account with API access** (available on all paid plans)

**Note**: The server uses `node-fetch` for HTTP requests. Node 18+ is required for development tools (ESLint, Vitest).

## 🔧 Local Development

### 1. Clone the repository

```bash
git clone https://github.com/your-username/deployhq-mcp-server.git
cd deployhq-mcp-server
```

### 2. Install dependencies

```bash
npm install
```

### 3. Run tests

```bash
npm test              # Run tests once
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run test:ui       # Run tests with UI
```

### 4. Build the project

```bash
npm run build
```

### 5. Test stdio transport locally

```bash
# Build first
npm run build

# Test with environment variables
DEPLOYHQ_EMAIL="your-email@example.com" \
DEPLOYHQ_API_KEY="your-api-key" \
DEPLOYHQ_ACCOUNT="your-account" \
node dist/stdio.js
```

The server will start in stdio mode and wait for JSON-RPC messages on stdin.

### 6. Test with Claude Code

Configure your local `.claude.json` to use the built version:

```json
{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}
```

## 🧪 Testing

The project includes a comprehensive test suite using Vitest:

**Test Coverage:**
- ✅ **Tool Schema Validation** - All 18 MCP tool schemas with valid/invalid inputs
- ✅ **API Client Methods** - All DeployHQ API methods with mocked responses
- ✅ **Error Handling** - Authentication, validation, and network errors
- ✅ **MCP Server Factory** - Server creation and configuration

**Running Tests:**
```bash
npm test              # Run all tests
npm run test:watch    # Watch mode for development
npm run test:coverage # Generate coverage report
npm run test:ui       # Interactive UI for debugging
```

**Test Stats:**
- 216 tests across 10 test suites
- Covers tools, api-client, and mcp-server modules
- Uses mocked fetch for isolated unit testing

## 🔒 Security

### Read-Only Mode (Optional)

**By default, the MCP server allows all operations, including creating deployments.**

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [deployhq](https://github.com/deployhq)
- **Source:** [deployhq/deployhq-mcp-server](https://github.com/deployhq/deployhq-mcp-server)
- **License:** MIT
- **Homepage:** https://deployhq.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-deployhq-deployhq-mcp-server
- Seller: https://agentstack.voostack.com/s/deployhq
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.