@vibecloud/mcp-server

An MCP (Model Context Protocol) server that lets AI assistants like Claude Code and Cursor interact with the VibeCloud API to provision cloud dev environments, deploy to production, manage storage, configure domains, handle secrets, and more.

98 tools | 4 MCP resources | 4 MCP prompts | 23 CLI guide tasks

Installation

npm install -g @vibecloud/mcp-server

Or run directly with npx:

npx @vibecloud/mcp-server

Or build from source:

cd mcp-server
npm install
npm run build

Prerequisites

• Node.js 18+ (for native fetch support)
• A VibeCloud account at vibecloud.sh

Quick Start

1. Configure Claude Code

Add the VibeCloud MCP server to your Claude Code configuration. Edit ~/.claude.json and add an mcpServers entry.

Option A: API Key (recommended for CI/programmatic use)

{
  "mcpServers": {
    "vibecloud": {
      "command": "vibecloud-mcp",
      "env": {
        "VIBECLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option B: JWT token

{
  "mcpServers": {
    "vibecloud": {
      "command": "vibecloud-mcp",
      "env": {
        "VIBECLOUD_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Option C: Automatic via CLI login (recommended for local development)

If you have the VibeCloud CLI installed, run vibe login and the MCP server automatically picks up the JWT from ~/.vibe/config.json:

{
  "mcpServers": {
    "vibecloud": {
      "command": "vibecloud-mcp"
    }
  }
}

If installed from source, use node /absolute/path/to/mcp-server/dist/index.js as the command.

2. Restart Claude Code

After adding the configuration, restart Claude Code. The VibeCloud tools will appear in Claude's available tools.

Authentication

The MCP server resolves credentials in priority order:

1. API Key (VIBECLOUD_API_KEY env var) — sent as X-API-Key header
2. JWT token (VIBECLOUD_API_TOKEN env var) — sent as Bearer token
3. Shared CLI config — reads JWT from ~/.vibe/config.json (shared with vibe login)
4. Login via tool — use the vibecloud_login tool with email/password

JWT tokens are automatically refreshed on expiration.

Available Tools (98)

All tools include MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to help AI clients make smarter tool choices.

Authentication

| Tool | Description | |------|-------------| | vibecloud_login | Authenticate with email/password, stores JWT | | vibecloud_register | Create a new VibeCloud account |

User Profile

| Tool | Description | |------|-------------| | vibecloud_whoami | Get current user's profile (email, name, ID) | | vibecloud_update_profile | Update profile fields |

Dashboard & Workflows

| Tool | Description | |------|-------------| | vibecloud_dashboard | Unified account overview in a single call | | vibecloud_environment_summary | Comprehensive summary of one environment | | vibecloud_wait_for_ready | Poll until an environment finishes provisioning | | vibecloud_quick_deploy | Create and fully configure a deployment in one call | | vibecloud_ssh_info | Get ready-to-use SSH connection command |

Projects

| Tool | Description | |------|-------------| | vibecloud_list_projects | List all projects | | vibecloud_get_project | Get project by ID or name | | vibecloud_create_project | Create a new project | | vibecloud_update_project | Update project settings | | vibecloud_delete_project | Delete a project |

API Keys

| Tool | Description | |------|-------------| | vibecloud_list_api_keys | List all API keys | | vibecloud_get_api_key | Get API key details | | vibecloud_create_api_key | Create a new API key with scopes | | vibecloud_update_api_key | Update an API key | | vibecloud_delete_api_key | Revoke an API key |

Environments

| Tool | Description | |------|-------------| | vibecloud_create_environment | Create a new cloud dev environment | | vibecloud_list_environments | List all environments | | vibecloud_get_environment | Get environment by ID or name | | vibecloud_update_environment | Update environment settings | | vibecloud_start_environment | Start a stopped environment | | vibecloud_stop_environment | Stop a running environment | | vibecloud_delete_environment | Delete an environment | | vibecloud_get_environment_status | Get provisioning and server status |

Instances

| Tool | Description | |------|-------------| | vibecloud_list_instances | List all compute instances | | vibecloud_get_instance | Get instance details | | vibecloud_get_instance_metrics | Get CPU, memory, GPU metrics | | vibecloud_cancel_shutdown | Cancel pending auto-shutdown |

Deployments

| Tool | Description | |------|-------------| | vibecloud_deploy | Create a production deployment with DNS/SSL | | vibecloud_list_deployments | List all deployments | | vibecloud_get_deployment | Get deployment by ID or app name | | vibecloud_update_deployment | Update deployment settings | | vibecloud_delete_deployment | Delete a deployment | | vibecloud_stop_deployment | Stop a deployment (removes DNS) | | vibecloud_check_deployment_health | Probe deployment health endpoints | | vibecloud_enable_hosting | Enable always-on hosting | | vibecloud_disable_hosting | Disable always-on hosting | | vibecloud_connect_github | Connect GitHub repo for auto-deploy | | vibecloud_disconnect_github | Disconnect GitHub auto-deploy |

Secrets

| Tool | Description | |------|-------------| | vibecloud_create_secret_identity | Provision Infisical machine identity |

Environment Variables

| Tool | Description | |------|-------------| | vibecloud_set_env_var | Set a single environment variable | | vibecloud_list_env_vars | List env vars (values masked) | | vibecloud_delete_env_var | Delete an environment variable | | vibecloud_batch_set_env_vars | Set multiple env vars at once (array of key-value pairs) | | vibecloud_batch_delete_env_vars | Delete multiple env vars at once |

Domains

| Tool | Description | |------|-------------| | vibecloud_list_domains | List all custom domains | | vibecloud_setup_domain | Set up a custom domain for a deployment | | vibecloud_verify_domain | Verify DNS configuration | | vibecloud_delete_domain | Remove a custom domain |

Storage Buckets

| Tool | Description | |------|-------------| | vibecloud_create_bucket | Create an S3-compatible storage bucket | | vibecloud_list_buckets | List all storage buckets | | vibecloud_get_bucket | Get bucket details by ID | | vibecloud_get_bucket_by_name | Look up bucket by name | | vibecloud_get_bucket_credentials | Get S3 access credentials | | vibecloud_delete_bucket | Delete a bucket |

Servers

| Tool | Description | |------|-------------| | vibecloud_list_servers | List all bare-metal servers | | vibecloud_get_server | Get server details | | vibecloud_create_server | Provision a new bare-metal server | | vibecloud_power_on_server | Power on a server | | vibecloud_power_off_server | Power off a server | | vibecloud_delete_server | Delete a server |

SSH Keys

| Tool | Description | |------|-------------| | vibecloud_list_ssh_keys | List registered SSH keys | | vibecloud_create_ssh_key | Register a new SSH public key | | vibecloud_delete_ssh_key | Remove an SSH key |

Organizations

| Tool | Description | |------|-------------| | vibecloud_list_organizations | List organizations you belong to | | vibecloud_get_organization | Get organization details | | vibecloud_get_organization_members | List organization members | | vibecloud_get_organization_projects | List organization projects |

Billing

| Tool | Description | |------|-------------| | vibecloud_billing_status | Get subscription and billing status | | vibecloud_list_tiers | List pricing tiers and features | | vibecloud_get_usage | Get current billing period usage | | vibecloud_create_checkout | Create Stripe checkout session | | vibecloud_create_portal | Open Stripe billing portal |

Billing Add-Ons

| Tool | Description | |------|-------------| | vibecloud_list_add_ons | List active add-ons | | vibecloud_create_add_on | Purchase an add-on | | vibecloud_delete_add_on | Remove an add-on |

Certificates

| Tool | Description | |------|-------------| | vibecloud_get_certificate | Get certificate details | | vibecloud_download_certificate | Download certificate files | | vibecloud_create_client_cert | Create a client certificate for mTLS | | vibecloud_revoke_certificate | Revoke a certificate |

Network

| Tool | Description | |------|-------------| | vibecloud_create_network_auth_key | Create VPN network auth key (Tailscale) |

Marketplace Services

| Tool | Description | |------|-------------| | vibecloud_list_marketplace_services | List available managed services | | vibecloud_get_marketplace_service | Get service details by slug | | vibecloud_list_service_subscriptions | List active subscriptions | | vibecloud_get_service_subscription | Get subscription details | | vibecloud_subscribe_service | Subscribe to a managed service | | vibecloud_unsubscribe_service | Cancel a subscription | | vibecloud_get_service_usage | Get usage stats for a subscription | | vibecloud_create_service_api_key | Create API key for a service | | vibecloud_list_service_api_keys | List service API keys | | vibecloud_delete_service_api_key | Revoke a service API key |

TurboBoost

| Tool | Description | |------|-------------| | vibecloud_turboboost_start | Start GPU TurboBoost session ($2.99/hr) | | vibecloud_turboboost_stop | Stop TurboBoost and finalize billing | | vibecloud_turboboost_status | Get TurboBoost status and cost |

CLI Guide

| Tool | Description | |------|-------------| | vibecloud_cli_guide | Get CLI command guidance for SSH-based tasks |

MCP Resources

The server exposes MCP resources that AI clients can read proactively:

| Resource | URI | Description | |----------|-----|-------------| | CLI Reference | vibecloud://cli-reference | Complete CLI command reference (23 tasks) | | Account Dashboard | vibecloud://account/dashboard | Live account overview with all environments, deployments, billing |

Resource Templates (parameterized):

| Template | URI Pattern | Description | |----------|-------------|-------------| | Environment Details | vibecloud://environments/{id} | Environment info with status | | Deployment Details | vibecloud://deployments/{id} | Deployment info with hosting status |

MCP Prompts

Pre-built workflow prompts that guide AI assistants through common tasks:

| Prompt | Arguments | Description | |--------|-----------|-------------| | deploy-app | app_name, server_ip | Step-by-step deployment guide | | debug-environment | environment_id | Troubleshooting checklist | | setup-dev-env | (none) | Getting-started guide (sync + SSH workflows) | | connect-domain | domain, deployment_id | Domain and DNS setup guide |

CLI Guide Tasks (23)

The vibecloud_cli_guide tool provides guidance for CLI commands that require SSH access or local binaries. Pass a task name to get the relevant commands:

| Task | Description | |------|-------------| | logs | Stream logs from the remote environment | | firewall | Manage UFW firewall rules | | health | Run comprehensive diagnostics | | inspect | Docker container diagnostics | | export | Export data from remote environment | | sync | Manage Mutagen file synchronization | | tunnel | Manage Tailscale VPN tunnel | | bucket-sync | Sync, mount, and export S3 buckets via rclone | | ssh | Direct SSH into the remote environment | | recover | Re-establish all connections after disconnection | | detect | Auto-detect project framework | | status | Full environment status dashboard | | up | Provision VM and establish connections | | down | Stop or terminate the environment | | deploy-promote | Safe production promotion with volume snapshots | | deploy-rollback | Rollback to previous deployment | | deploy-logs | Stream deployment container logs | | storage | Manage NVMe block storage volumes | | eject | Generate standalone project files for any provider | | debug | Debug shell into remote containers | | events | Stream real-time WebSocket events | | sessions | Manage tracked project sessions | | init | Initialize project configuration |

Name-Based Resolution

The following tools accept either an ID or a name, so you don't need to know UUIDs:

• vibecloud_get_project — pass name instead of project_id
• vibecloud_get_environment — pass name instead of environment_id
• vibecloud_get_deployment — pass name instead of deployment_id (matches app_name)

Example Conversations

• "Who am I on VibeCloud?" (uses vibecloud_whoami)
• "Show me my dashboard" (uses vibecloud_dashboard)
• "Create a new environment called 'my-saas-app' with the gpu-l40s-1x plan"
• "Wait for my environment to be ready" (uses vibecloud_wait_for_ready)
• "Deploy my app to production on server 203.0.113.42" (uses vibecloud_quick_deploy)
• "Set DATABASE_URL and SECRET_KEY on my deployment" (uses vibecloud_batch_set_env_vars)
• "Set up the custom domain myapp.com" (uses vibecloud_setup_domain)
• "How do I check my deployment logs?" (uses vibecloud_cli_guide with task deploy-logs)
• "What's my current billing status?" (uses vibecloud_billing_status)
• "Start a TurboBoost GPU session" (uses vibecloud_turboboost_start)

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | VIBECLOUD_API_KEY | (none) | API key (sent as X-API-Key header) | | VIBECLOUD_API_TOKEN | (none) | JWT token (sent as Bearer token) | | VIBECLOUD_API_URL | https://api.vibecloud.sh | API base URL |

Development

# Watch mode
npm run dev

# Test with MCP inspector
npx @modelcontextprotocol/inspector node dist/index.js

Architecture

mcp-server/
  src/
    index.ts    # MCP server — 98 tools, resources, prompts, and handlers
    api.ts      # VibeCloud API client — HTTP methods for all endpoints
  dist/         # Compiled JavaScript (generated by npm run build)
  package.json
  tsconfig.json

The server communicates over stdio using JSON-RPC, following the MCP specification. Each tool maps to one or more VibeCloud REST API endpoints. The API client handles authentication, error formatting, JWT auto-refresh, and token persistence.

License

MIT