npm package: @iflow-mcp/deployhq_deployhq-mcp-server
Description: Model Context Protocol (MCP) server for DeployHQ API integration
Author: DeployHQ Team
Latest version: 1.2.2

# 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 **7 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_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

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

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

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

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

**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 7 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:**
- 50+ tests across 3 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.** This is the recommended configuration for most users.

For users who want additional protection against accidental deployments, the server includes an **optional read-only mode** that can be enabled to block deployment creation.

**Default Behavior (No Configuration Needed):**
- ✅ Deployments are **allowed by default**
- ✅ All operations work: list, get, and create deployments
- ✅ Full functionality out of the box

**When you might want to enable read-only mode:**
- You want extra protection against accidental deployments via AI
- You're connecting to production environments and want an additional safety layer
- You only need read access to monitor deployments
- You're still testing the integration and want to be cautious

**Important:** Read-only mode is **completely optional**. The server works fully without it.

**How to enable read-only mode:**

Via environment variable:
```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",
        "DEPLOYHQ_READ_ONLY": "true"
      }
    }
  }
}
```

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

**Configuration precedence:**
1. CLI flag `--read-only` (highest priority)
2. Environment variable `DEPLOYHQ_READ_ONLY`
3. Default value: `false` (deployments allowed)

### Additional Security Notes

- **Deployment Logs May Contain Secrets**: Deployment logs can include environment variables, API keys, and other sensitive information. Exercise caution when using tools that retrieve logs, especially with third-party AI services.

- **Use Least-Privilege API Keys**: Create dedicated API keys with minimum required permissions for MCP access. Consider separate keys for read-only vs. read-write operations.

- **Audit MCP Activity**: Monitor MCP usage, especially in production environments. Review logs regularly for unexpected behavior.

- **Environment Variables**: Credentials are never stored, only passed via environment variables

- **HTTPS**: When using npx, credentials stay local to your machine

- **No Telemetry**: No data is sent anywhere except directly to DeployHQ API

---

## 🌐 Optional: Hosted Deployment

The server can also be deployed as a hosted service with SSE/HTTP transports. This is useful for web integrations or shared team access.

### 🚀 Deployment to Digital Ocean

### Option 1: Using the Dashboard

1. **Prepare your repository**:
   ```bash
   git add .
   git commit -m "Initial commit"
   git push origin main
   ```

2. **Create a new app**:
   - Go to [Digital Ocean Apps](https://cloud.digitalocean.com/apps)
   - Click "Create App"
   - Select your GitHub repository
   - Choose the branch (main)

3. **Configure the app**:
   - Digital Ocean will detect the Dockerfile automatically
   - Or use the `.do/app.yaml` configuration

4. **Set environment variables**:
   - Go to App Settings → Environment Variables
   - Add the following as **encrypted** variables:
     - `DEPLOYHQ_EMAIL`
     - `DEPLOYHQ_API_KEY`
     - `DEPLOYHQ_ACCOUNT`
   - Add these as regular variables:
     - `NODE_ENV=production`
     - `PORT=8080`
     - `LOG_LEVEL=info`

5. **Deploy**:
   - Click "Next" and "Create Resources"
   - Wait for deployment to complete

6. **Configure custom domain** (optional):
   - Go to Settings → Domains
   - Add `mcp.deployhq.com`
   - Update your DNS records as instructed

### Option 2: Using doctl CLI

1. **Install doctl**:
   ```bash
   # macOS
   brew install doctl

   # Linux
   cd ~
   wget https://github.com/digitalocean/doctl/releases/download/v1.104.0/doctl-1.104.0-linux-amd64.tar.gz
   tar xf doctl-1.104.0-linux-amd64.tar.gz
   sudo mv doctl /usr/local/bin
   ```

2. **Authenticate**:
   ```bash
   doctl auth init
   ```

3. **Update `.do/app.yaml`**:
   - Edit the `github.repo` field with your repository
   - Review and adjust instance size if needed

4. **Create the app**:
   ```bash
   doctl apps create --spec .do/app.yaml
   ```

5. **Set environment secrets**:
   ```bash
   # Get your app ID
   doctl apps list

   # Update environment variables (replace APP_ID)
   doctl apps update APP_ID --spec .do/app.yaml
   ```

6. **View logs**:
   ```bash
   doctl apps logs APP_ID --follow
   ```

### 🔒 Hosted Security

- **Never commit credentials**: Use `.env` for local development (excluded by `.gitignore`)
- **Use Digital Ocean secrets**: Store credentials as encrypted environment variables
- **HTTPS only**: Digital Ocean provides automatic HTTPS
- **Minimal permissions**: Use a dedicated DeployHQ user with minimum required permissions

### 📊 Hosted Monitoring

#### Health Check

The hosted server includes a health check endpoint at `/health`:

```bash
curl https://mcp.deployhq.com/health
```

#### Logs

View logs in Digital Ocean:
- Dashboard: Go to your app → Runtime Logs
- CLI: `doctl apps logs <APP_ID> --follow`

#### Alerts

Digital Ocean will alert you on:
- Deployment failures
- Domain configuration issues
- Health check failures

### 🧪 Testing Hosted Server

Test the SSE endpoint:

```bash
curl -N http://localhost:8080/sse \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account"
```

Test the HTTP transport endpoint:

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'
```

See the hosted deployment documentation for full testing examples.

## 📚 Project Structure

```
deployhq-mcp-server/
├── src/
│   ├── stdio.ts          # stdio transport entrypoint (for Claude Desktop/Code)
│   ├── index.ts          # Express server (for hosted deployment)
│   ├── mcp-server.ts     # Core MCP server factory (shared)
│   ├── tools.ts          # Tool definitions and schemas (shared)
│   ├── api-client.ts     # DeployHQ API client (shared)
│   ├── transports/       # SSE/HTTP handlers (for hosted)
│   └── utils/            # Logging and utilities
├── docs/
│   ├── claude-config.json          # Universal config template (Desktop & Code)
│   ├── USER_GUIDE.md               # User documentation
│   ├── DEPLOYMENT.md               # Hosted deployment guide
│   └── HTTP_TRANSPORT.md           # HTTP transport documentation
├── .do/
│   └── app.yaml          # Digital Ocean configuration (optional)
├── Dockerfile            # Container configuration (optional)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── STDIO_MIGRATION.md    # stdio migration documentation
└── README.md             # This file
```

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

### For Maintainers

See [RELEASING.md](RELEASING.md) for instructions on creating releases and publishing to npm.

## 📄 License

MIT License - see LICENSE file for details

## 🆘 Support

- **DeployHQ API Documentation**: https://www.deployhq.com/support/api
- **MCP Documentation**: https://modelcontextprotocol.io
- **Issues**: https://github.com/deployhq/deployhq-mcp-server/issues

## 🔗 Related Links

- [DeployHQ](https://www.deployhq.com)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Digital Ocean App Platform](https://www.digitalocean.com/products/app-platform)
- [Claude Desktop](https://claude.ai/desktop)
- [Claude Code CLI](https://github.com/anthropics/claude-code)