Skip to content

Latest commit

 

History

History
119 lines (87 loc) · 2.91 KB

README.md

File metadata and controls

119 lines (87 loc) · 2.91 KB

gce-ops-mcp

MCP server for Google Compute Engine operations.

Capabilities

  • Health and auth checks for local gcloud setup
  • Start instances with retry logic (capacity-sensitive zones)
  • Stop instances with explicit Local SSD behavior
  • Query instance status and metadata
  • List currently running GPU instances in a project
  • Persist per-instance zone mappings

Tool Reference

Tool Purpose
health() Validate gcloud and active auth context
set_zone(instance_name, zone) Save a preferred zone for an instance
list_zones() Show saved instance→zone mappings
instance_status(instance_name, project_id?, zone?) Get status + metadata
list_running_gpu_instances(project_id?) List all running GPU instances
start_instance(instance_name, project_id?, zone?, interval_seconds?, max_attempts?) Start with retry loop
stop_instance(instance_name, project_id?, zone?, discard_local_ssd=true) Stop instance, defaulting to Local SSD discard

Notes:

  • project_id is required unless GCP_PROJECT_ID is set.
  • stop_instance defaults discard_local_ssd=true because GCP requires explicit handling for Local SSD VMs.

Installation

cd servers/gce-ops-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Run Standalone

source .venv/bin/activate
python -m gce_ops_mcp.server

Configuration

Optional environment variables:

export GCP_PROJECT_ID="your-project-id"
export GCP_MCP_RETRY_INTERVAL_SECONDS=15
export GCP_MCP_MAX_ATTEMPTS=40
# export GCP_MCP_ZONES_FILE="$HOME/.config/gce-ops-mcp/zones.tsv"

MCP Client Setup

Codex

[mcp_servers.gcloud-mcp]
command = "/ABSOLUTE/PATH/TO/mcp-tools/scripts/run-gce-ops-mcp.sh"

Claude Desktop

Use the same launcher command path in your Claude MCP server entry.

Assistant Usage (Codex/Claude)

Natural-language examples:

  • Turn on google-gpu in project reach-465609 and zone us-central1-a.
  • Check whether google-gpu is running in reach-465609.
  • Stop google-gpu in us-central1-a.

Parameter guidance:

  • project_id is required unless you set GCP_PROJECT_ID.
  • zone is optional; if omitted, the server checks saved mappings and then auto-detects.
  • For the first call on a new instance, passing both project_id and zone is usually best.

Examples

List running GPU instances:

list_running_gpu_instances(project_id="my-project")

Start an instance with retries:

start_instance(
  instance_name="gpu-trainer-a100",
  project_id="my-project",
  zone="us-central1-a",
  interval_seconds=20,
  max_attempts=60
)

Stop an instance:

stop_instance(
  instance_name="gpu-trainer-a100",
  project_id="my-project",
  zone="us-central1-a",
  discard_local_ssd=true
)

Safety

  • This server issues real gcloud compute operations.
  • Use least-privilege IAM where possible.
  • Validate project/zone before start/stop calls.