GitHub - deployhq/deployhq-mcp-server: DeployHQ MCP Server (original) (raw)

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

📋 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:

list_servers

List all servers configured for a project.

Parameters:

list_deployments

List deployments for a project with pagination support.

Parameters:

get_deployment

Get detailed information about a specific deployment.

Parameters:

get_deployment_log

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

Parameters:

Returns: Complete deployment log as text

create_deployment

Create a new deployment for a project.

Parameters:

🚀 Quick Start

Easy Installation with Claude Code

The fastest way to install for Claude Code:

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:

Then restart Claude Desktop.

For Claude Code:

Add to your .claude.json file in your project directory.

Configuration:

{ "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:

💡 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

Optional

Log Levels

Control verbosity with the LOG_LEVEL environment variable:

Example:

{ "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:

Authentication Errors

Problem: "Authentication failed" or 401/403 errors

Solutions:

Project Not Found

Problem: "Project not found" or 404 errors

Solutions:

Deployment Creation Blocked

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

Solution:

Deployment Fails

Problem: Deployment created but fails immediately

Solutions:

Connection Timeouts

Problem: "Request timeout" errors

Solutions:

Logs Not Showing

Problem: Not seeing any log output

Solutions:

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  │
└─────────────────┘                    └─────────────┘

📦 Prerequisites

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

🔧 Local Development

1. Clone the repository

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

2. Install dependencies

3. Run tests

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

5. Test stdio transport locally

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:

{ "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:

Running Tests:

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:

🔒 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):

When you might want to enable read-only mode:

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

How to enable read-only mode:

Via environment variable:

{ "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:

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

🌐 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:
    git add .
    git commit -m "Initial commit"
    git push origin main
  2. Create a new app:
    • Go to Digital Ocean 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:

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: 3. Update .do/app.yaml:

  1. Create the app:
    doctl apps create --spec .do/app.yaml
  2. Set environment secrets:

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:
doctl apps logs APP_ID --follow

🔒 Hosted Security

📊 Hosted Monitoring

Health Check

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

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

Logs

View logs in Digital Ocean:

Alerts

Digital Ocean will alert you on:

🧪 Testing Hosted Server

Test the SSE endpoint:

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:

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 for instructions on creating releases and publishing to npm.

📄 License

MIT License - see LICENSE file for details

🆘 Support