MCP Client
   │
   │  Authorization: Bearer <base64_sa_key>
   ▼
┌──────────────────────────────────────┐
│  main.py  (Starlette ASGI app)       │
│  ├── GET  /sse       → SSE stream   │
│  ├── POST /messages/ → MCP messages  │
│  └── GET  /health    → health check  │
│                                      │
│  src/auth.py → decode token, set ctx │
│  src/server.py → shared FastMCP instance │
│                                      │
│  src/tools/compute.py     (5 tools)  │
│  src/tools/networking.py  (17 tools) │
│  src/tools/gke.py         (4 tools)  │
│  src/tools/regions.py     (4 tools)  │
│  src/tools/inventory.py   (3 tools)  │
│                                      │
│  src/gcp_clients.py → client factories│
└──────────────────────────────────────┘
   │
   ▼
Google Cloud APIs  (Compute, Container, DNS, Asset Inventory)

cd gcpmcp

# Create and activate a virtual environment
python -m venv venv

# Linux / macOS
source venv/bin/activate

# Windows (PowerShell)
.\venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

docker build -t gcp-mcp-server .

python main.py

python main.py --host 127.0.0.1 --port 9000 --log-level debug

docker run -p 8080:8080 gcp-mcp-server

curl http://localhost:8080/health
# {"status":"healthy","server":"gcp-infrastructure-mcp"}

PROJECT_ID=your-project-id

# Create the service account
gcloud iam service-accounts create mcp-reader \
    --display-name="MCP Infrastructure Reader"

# Grant read-only roles
for ROLE in roles/compute.viewer roles/container.viewer \
            roles/dns.reader roles/cloudasset.viewer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member="serviceAccount:mcp-reader@${PROJECT_ID}.iam.gserviceaccount.com" \
      --role="$ROLE"
done

# Download the JSON key
gcloud iam service-accounts keys create sa-key.json \
    --iam-account=mcp-reader@${PROJECT_ID}.iam.gserviceaccount.com

TOKEN=$(base64 -w 0 < sa-key.json)
echo "$TOKEN"

$TOKEN = [Convert]::ToBase64String([IO.File]::ReadAllBytes("sa-key.json"))
Write-Output $TOKEN

{
  "mcpServers": {
    "gcp-infrastructure": {
      "url": "http://localhost:8080/sse",
      "token": "<BASE64_ENCODED_SERVICE_ACCOUNT_KEY>"
    }
  }
}

{
  "mcpServers": {
    "gcp-infrastructure": {
      "url": "https://mcp.example.com/sse",
      "token": "<BASE64_ENCODED_SERVICE_ACCOUNT_KEY>"
    }
  }
}

User:  "List all VPCs and generate Terraform for them"
AI:    → calls list_vpcs → gets 3 VPCs with auto-subnets
       → calls list_subnets → maps CIDRs per region
       → generates google_compute_network + google_compute_subnetwork resources

# src/tools/storage.py  (example)
from src.server import mcp
from src.auth import get_credentials, get_project_id
from src.gcp_clients import run_sync, format_response

@mcp.tool()
async def list_storage_buckets(project_id=None, max_results=100):
    """List Cloud Storage buckets."""
    credentials = get_credentials()
    project = project_id or get_project_id()
    # ... call GCS API ...

import src.tools.storage  # noqa: F401

gcpmcp/
├── main.py                  # Entry point — HTTP server + route handlers
├── src/
│   ├── __init__.py
│   ├── server.py            # Shared FastMCP instance
│   ├── auth.py              # Token decoding + per-session credential mgmt
│   ├── gcp_clients.py       # GCP client factories + proto-to-dict helpers
│   └── tools/
│       ├── __init__.py
│       ├── compute.py       # Compute Engine tools  (5)
│       ├── networking.py    # VPC / firewall / DNS / LB tools  (17)
│       ├── gke.py           # GKE tools  (4)
│       ├── regions.py       # Region & zone tools  (4)
│       └── inventory.py     # Cloud Asset Inventory tools  (3)
├── requirements.txt         # Python dependencies
├── Dockerfile               # Container image
└── README.md                # This file