GCP Model Context Protocol (MCP) Orchestrator

A robust intermediary service engineered to interface MCP-enabled Artificial Intelligence agents (such as advanced LLM IDEs) with the comprehensive functionality of the Google Cloud Command Line Interface (gcloud). This service ensures secure command dispatch, output sanitization, and context awareness within a containerized deployment model.

Core Functionality

This orchestrator acts as a secure proxy, enabling AI systems to systematically interact with GCP resources by providing two primary capabilities:

1. Schema Retrieval (gcloud_documentation): Instantly fetches up-to-date official documentation and usage parameters for any gcloud component.
2. Command Execution (gcloud_pipeline): Executes complex gcloud sequences, incorporating standard Unix command piping (|) and filtering for optimized, AI-consumable results.

mermaid flowchart TD AI[Intelligent Agent (MCP Client)] <-->|Protocol Interaction| Bridge[GCP MCP Orchestrator] Bridge <-->|Subprocess Execution| GCLOUD[gcloud CLI] GCLOUD <-->|Service Calls| GCP_API[Google Cloud Platform Services]

Key Attributes

• Secure Execution Context: All operations are sandboxed within a Docker container, drastically limiting potential host impact.
• Multi-Architecture: Built natively for x86_64 (Intel/AMD) and AArch64 (ARM/Graviton) systems.
• Unix Pipeline Support: Allows chaining commands (e.g., gcloud compute instances list | jq .) for advanced data manipulation.
• Contextual Awareness (MCP Resources): Provides the agent with readily available GCP credentials context, active project IDs, and region configurations.
• Templated Workflows: Supports parameterized prompt templates for complex, repeatable GCP management tasks.
• Credential Agnostic: Seamlessly utilizes existing, host-provided GCP authentication methods.

Deployment Modalities

Deployment is achieved primarily via containerization, which is the mandated best practice for security and operational consistency.

Option 1: Container Orchestration (Recommended)

Leverage Docker Compose for straightforward setup:

bash git clone https://github.com/user/gcp-mcp-bridge.git cd gcp-mcp-bridge

Deploy in detached mode

docker compose up -d

Images are available on the container registry, supporting multi-arch pulls:

bash

Latest stable build

docker pull ghcr.io/user/gcp-mcp-bridge:stable

Version pinned (e.g., v1.5.0)

docker pull ghcr.io/user/gcp-mcp-bridge:v1.5.0

Option 2: Native Python Execution (Use with Caution)

For environments where containerization is infeasible, native setup is possible. This path requires manual dependency management and inherently carries higher risk:

bash

Setup Python environment

python3 -m venv venv && source venv/bin/activate

pip install -e .[gcp-native]

Initiate the service

python -m gcp_mcp_bridge.server

Configuration Parameters

Configuration utilizes standard environment variables to dictate operational parameters:

Variable Name	Purpose	Default Value
GCP_MCP_SESSION_TTL	Maximum allowable command duration (seconds)	360
GCP_MCP_MAX_RESPONSE_BYTES	Cap on output payload size	150000
GCP_MCP_INTERFACE	Communication mechanism ("stdio" or "http_sse")	stdio
CLOUDSDK_CORE_PROJECT	Default GCP Project ID to utilize	(Inherited from environment)
CLOUDSDK_COMPUTE_ZONE	Default Compute Zone	us-central1-a
GCP_MCP_LOCKDOWN_LEVEL	Security enforcement mode ("enforce" or "audit")	enforce

Security Mandates and Isolation

Security is the foundational design principle. The architecture emphasizes defense-in-depth, primarily relying on container isolation and stringent command filtering.

1. Containerization: The Primary Barrier

Executing within Docker is non-negotiable for secure operation. This isolates the execution context, preventing malicious or erroneous shell commands from achieving persistence or modifying the host operating system's filesystem or processes.

2. IAM Principle of Least Privilege (Critical)

The service inherits the credentials provided to it (via gcloud auth application-default login or mounted configuration). It is imperative that these credentials belong to an identity granted the absolute minimum required IAM permissions (Least Privilege). This policy configuration forms the ultimate control boundary, as no executed command can exceed the permissions granted to the underlying service account or user.

3. Command Validation Layer

The orchestrator employs a rigorous, multi-stage inspection process before executing any command:

• Syntax Check: Initial verification of command structure (must start with gcloud).
• Keyword Filtering: Explicitly blocks high-risk verbs associated with credential manipulation, logging disruption, or resource destruction.
• Pipe Sanitization: Scrutinizes any chained Unix utilities (e.g., grep, awk, xargs) against a predefined safe allowlist to prevent command injection.

High-Risk Command Blocklist (Examples)

Commands related to IAM modification, logging cessation, or resource destruction are typically forbidden:

• IAM Tampering: gcloud iam service-accounts create, gcloud iam policies set-iam-policy, gcloud iam keys create.
• Audit Disruption: gcloud logging sinks delete, gcloud audit-logs disable.
• Destructive Actions: gcloud compute instances delete, gcloud storage buckets delete.

Allowed Operations: All standard read operations (all commands prefixed with describe-, list-, get-) are permitted by default, provided they do not violate other filtering rules.

Security Modes

• enforce (Default): Blocks any detected risky operation and reports an error.
• audit: Executes the command but logs a high-severity warning if a potentially risky pattern is matched, offering visibility without immediate termination.

Available Service Templates

The service exposes numerous pre-configured operational templates to guide the AI agent toward secure and efficient GCP interactions.

Template Name	Functionality Description	Required Arguments
gcp_deploy_vm	Generates idempotent commands for spinning up Compute Engine instances.	instance_name, zone, machine_type
gcp_inventory_gcs	Outputs a detailed, filtered inventory of all Cloud Storage buckets.	project_id (optional)
gcp_iam_reader	Creates a policy granting only *.get and *.list permissions for specified services.	services_list
gcp_k8s_status	Retrieves aggregated status across all GKE clusters in a region.	region
gcp_cleanup_stale_resources	Identifies and generates commands to delete resources older than a threshold.	resource_type, age_days

Development & Contribution

This project welcomes contributions. The development workflow prioritizes code quality and testing.

Setup

Use the provided Makefile targets for standardized tasks:

bash make setup-dev # Installs all required dependencies, including testing tools make check-code # Runs static analysis (linting) make run-tests # Executes all unit tests

Integration Testing

Integration tests validate against live GCP infrastructure. Before running:

1. Ensure environment variables like CLOUDSDK_CORE_PROJECT and authentication are set.
2. Define a dedicated test project/bucket.
3. Execute with the appropriate pytest marker: bash pytest --marker=integration

Licensing

Distributed under the Apache License 2.0. Refer to the LICENSE file for comprehensive details.

---

Contextual Reference (Non-Tool Content): Google Cloud Platform (GCP) is Google's suite of public cloud services, built upon the same infrastructure powering Google Search and Gmail. It offers IaaS, PaaS, and serverless capabilities. Key compute offerings include App Engine, Compute Engine (VMs), Google Kubernetes Engine (GKE), and Cloud Functions. Storage solutions encompass Cloud Storage (object), Cloud SQL (relational), and Cloud Spanner (horizontally scalable relational DB). GCP is now commonly referred to simply as Google Cloud.