bosh-mcp-server

An MCP (Model Context Protocol) server that provides BOSH Director operations to AI assistants like Claude.

Features

• 18 BOSH tools for diagnostics, infrastructure inspection, and deployment operations
• Layered authentication: environment variables → ~/.bosh/config → Ops Manager
• Confirmation tokens for destructive operations (configurable)
• Async task handling: deployment operations wait for completion by default

Installation

From Source

git clone https://github.com/malston/bosh-mcp-server.git
cd bosh-mcp-server
go build -o bosh-mcp-server ./cmd/bosh-mcp-server

Binary

Download the latest release from the releases page.

Configuration

Authentication

The server resolves BOSH credentials in order of precedence:

1. Environment variables (highest priority)

   export BOSH_ENVIRONMENT=https://10.0.0.5:25555
   export BOSH_CLIENT=admin
   export BOSH_CLIENT_SECRET=secret
   export BOSH_CA_CERT=/path/to/ca.crt
   

2. BOSH config file (~/.bosh/config)

   • Standard BOSH CLI configuration format
   • Supports named environments

3. Ops Manager (fallback)

   export OM_TARGET=https://opsman.example.com
   export OM_USERNAME=admin
   export OM_PASSWORD=secret
   

   The server calls om bosh-env and caches credentials for 5 minutes.

Server Configuration

Optional configuration via ~/.bosh-mcp/config.yaml:

# Token TTL for confirmation tokens (seconds)
token_ttl: 300

# Operations requiring confirmation tokens
confirm_operations:
  - delete_deployment
  - recreate
  - stop
  - cck

# Operations blocked entirely
blocked_operations: []

Set BOSH_MCP_CONFIG to use a custom config path.

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bosh": {
      "command": "/path/to/bosh-mcp-server",
      "env": {
        "BOSH_ENVIRONMENT": "https://10.0.0.5:25555",
        "BOSH_CLIENT": "admin",
        "BOSH_CLIENT_SECRET": "your-secret",
        "BOSH_CA_CERT": "/path/to/ca.crt"
      }
    }
  }
}

Available Tools

Diagnostic Tools

| Tool | Description | |------|-------------| | bosh_vms | List VMs for a deployment | | bosh_instances | List instances with process details | | bosh_tasks | List recent BOSH tasks | | bosh_task | Get details of a specific task | | bosh_task_wait | Wait for a task to complete |

Infrastructure Tools

| Tool | Description | |------|-------------| | bosh_stemcells | List uploaded stemcells | | bosh_releases | List uploaded releases | | bosh_deployments | List all deployments | | bosh_cloud_config | Get current cloud config | | bosh_runtime_config | Get runtime configs | | bosh_cpi_config | Get CPI config | | bosh_variables | List variables for a deployment | | bosh_locks | Show current deployment locks |

Deployment Tools

| Tool | Description | Confirmation Required | |------|-------------|----------------------| | bosh_delete_deployment | Delete a deployment | Yes | | bosh_recreate | Recreate VMs | Yes | | bosh_stop | Stop jobs | Yes | | bosh_start | Start jobs | No | | bosh_restart | Restart jobs | No |

All deployment tools wait for task completion by default (configurable timeout).

Confirmation Token Flow

Destructive operations require a two-step confirmation:

1. Request operation (without confirm parameter):

   bosh_delete_deployment(deployment: "my-app")
   → {"requires_confirmation": true, "confirmation_token": "tok_abc123", ...}
   

2. Confirm operation (with token):

   bosh_delete_deployment(deployment: "my-app", confirm: "tok_abc123")
   → {"task_id": 456, "state": "done", ...}
   

Tokens expire after 5 minutes (configurable) and are single-use.

Development

Prerequisites

• Go 1.21+

Buil

... View full README on GitHub