GCP Infrastructure MCP Server

A Model Context Protocol (MCP) server that provides 30+ read-only tools for querying Google Cloud Platform infrastructure. Designed for AI assistants, Terraform workflow support, and any MCP-compatible client.

Each user authenticates with their own base64-encoded GCP service account key — no credentials are stored on the server.

Table of Contents

• Features
• Architecture
• Prerequisites
• Installation
• Running the Server
• Authentication Setup
• MCP Client Configuration
• Available Tools
• Terraform Integration
• Adding New Tools
• Security Considerations

Features

• 30+ infrastructure tools covering Compute, Networking, GKE, DNS, Load Balancers, and Cloud Asset Inventory
• Multi-tenant — each user provides their own service account key as a Bearer token
• SSE transport — works with any MCP client that supports URL + token
• Async — GCP API calls run in a thread pool to keep the event loop responsive
• Terraform-friendly — fetch real infrastructure state to generate or validate .tf files
• Docker-ready — ship as a single container

Architecture

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)

Prerequisites

Installation

Option A — Local (virtualenv)

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

Option B — Docker

docker build -t gcp-mcp-server .

Running the Server

Local

python main.py

Example:

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

Docker

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

Health Check

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

Authentication Setup

1. Create a GCP Service Account

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

2. Base64-Encode the Key

Linux / macOS:

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

Windows (PowerShell):

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

3. Required IAM Roles

MCP Client Configuration

Set your MCP client to connect with:

• URL: http://<server-host>:8080/sse
• Token: the base64-encoded service account key

Example — Generic MCP Client

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

Example — Production (HTTPS)

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

Note: Different users can connect simultaneously, each with their own token pointing to a different GCP project.

Available Tools

Compute Engine (5 tools)

Networking (7 tools)

IP Addresses (1 tool)

Load Balancers (6 tools)

SSL (1 tool)

DNS (2 tools)

GKE — Google Kubernetes Engine (4 tools)

Regions & Zones (4 tools)

Cloud Asset Inventory (3 tools)

Terraform Integration

This server is purpose-built for infrastructure-as-code workflows:

1. Audit — Use get_infrastructure_summary to see what's deployed.
2. Explore — Drill into VPCs, subnets, firewalls, GKE clusters.
3. Generate — Feed real infrastructure data to an AI to produce accurate .tf files.
4. Validate — Compare terraform plan output against live state.

Example Workflow

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

Adding New Tools

1. Pick the right file (src/tools/compute.py, src/tools/networking.py, etc.) or create a new src/tools/<name>.py module.
2. Import mcp from src.server and credentials helpers from src.auth.
3. Decorate your function with @mcp.tool().
4. If you create a new module, import it in main.py so the tools get registered.

# 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 ...

Then add to main.py:

import src.tools.storage  # noqa: F401

Project Structure

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

Security Considerations

License

MIT