What is Google Cloud Mcp Python

google-cloud-mcp-python is a modular Model Context Protocol (MCP) server designed for Google Cloud Platform (GCP). It facilitates the exposure of tools and resources such as metrics, logs, or custom logic for use by LLM agents or human clients, supporting multiple transport layers including stdio, SSE (Server-Sent Events), and HTTP.

Use cases

Use cases for google-cloud-mcp-python include developing applications that require real-time data processing, integrating LLMs with existing tools, and creating custom logging solutions for cloud-based applications.

How to use

To use google-cloud-mcp-python, you can select the desired transport layer via a command-line argument when starting the server. Ensure that your tools return errors using the shared Pydantic ErrorResponse class to maintain consistency and reliability.

Key features

Key features of google-cloud-mcp-python include modular design, support for multiple transport layers (stdio, SSE, HTTP), and a standardized error handling mechanism using Pydantic’s ErrorResponse class, which enhances machine parsability and debugging.

Where to use

google-cloud-mcp-python can be used in various fields such as cloud computing, machine learning, and application development, particularly where interaction with LLM agents or the need for structured logging and metrics is required.

Google Cloud MCP Python Server

Overview

This project is a modular Model Context Protocol (MCP) server for Google Cloud Platform (GCP).
It enables tools and resources (such as metrics, logs, or custom logic) to be exposed for use by LLM agents or human clients, supporting multiple transport layers: stdio, SSE (Server-Sent Events), and HTTP.
The desired transport can be selected via a command-line argument.

ErrorResponse Guide for Tool Error Handling

All tools should return errors using the shared Pydantic ErrorResponse class located in src/tools/models/error_response.py. This ensures consistency, reliability, and machine parsability across all interfaces (LLM, UI, automation).

Model Example:

from pydantic import BaseModel, Field
from typing import Any

class ErrorResponse(BaseModel):
    error: str = Field(..., description="Error message string")
    detail: str | None = Field(
        None,
        description="Optional detailed error information (stacktrace, exception repr, etc.)",
    )
    context: dict[str, Any] | None = Field(
        None,
        description="Optional extra context such as project_id, resource name, etc.",
    )

Usage Pattern in Tools:

try:
    # Tool logic...
except Exception as exc:
    return ErrorResponse(
        error=str(exc),
        detail=repr(exc),
        context={
            "project_id": project_id,
            "resource": resource_name,
            # ... add more context as needed ...
        }
    ).dict()

Returned JSON Example:

{
  "error": "Permission denied while starting instance.",
  "detail": "google.api_core.exceptions.Forbidden: 403 Permission denied",
  "context": {
    "project_id": "gcp-demo",
    "instance_name": "my-instance"
  }
}

Best Practices:

• Always return an ErrorResponse (never raise) from tool logic if failure occurs.
• Provide helpful context for debugging or automated retry.
• Use the detail field for stack traces, exception types, or anything for deeper troubleshooting.

Features

• 🟢 Modular MCP server (easily add more GCP tools/resources)
• 🚀 Supports stdio, HTTP, and Server-Sent Events (SSE) transports (selectable at startup via CLI)
• 🪝 Uses Application Default Credentials (ADC) for secure, flexible authentication
• 📊 Includes an example tool for Google Cloud Monitoring metrics retrieval
• 🧑‍💻 Idiomatic, well-documented, fully testable Python codebase

Getting Started

1. Install Dependencies

uv pip install -r requirements.txt
# or, with UV:
uv sync

2. Google Credentials

Set up Application Default Credentials (ADC guide):

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Or authenticate with gcloud:

gcloud auth application-default login

3. Run the Server (select transport)

You can choose the transport layer via the --transport (or -t) argument. Supported values: stdio, sse, or streamable-http.

a) Default (streamable-http)

python src/main.py

Runs an HTTP server accessible at http://localhost:8000/mcp.

b) HTTP explicitly

python src/main.py --transport streamable-http

c) SSE (Server-Sent Events)

python src/main.py --transport sse

Access the SSE endpoint (if implemented):

• Typically at http://localhost:8000/mcp/sse or http://localhost:8000/mcp/events
• Use an SSE client, browser EventSource, or compatible tool.

d) STDIO

python src/main.py --transport stdio

Runs the server in standard input/output mode (no HTTP endpoint).
Interact directly using CLI tools or programmatic stdin/stdout (common for LLM agents or parent processes).

Transport Layer Summary

Adding Tools

Implement new tools in the src/tools/ package. Import them in main.py to register with the MCP server.
Follow the docstring pattern below to ensure your tools are discoverable and well-documented for LLM agents.

📝 Tool Docstring Pattern & Guide

Use this format for all MCP tool functions:

@mcp.tool()
def tool_name(
    arg1: Type1,
    arg2: Type2,
    opt_arg3: Type3 = default_val,
) -> ReturnType:
    """
    [Short summary] (1-2 sentences)

    [Longer explanation or context if needed—why, when, or for whom this tool is useful.]

    Arguments:
        arg1 (Type1): [Description of the argument, acceptable values, examples...]
        arg2 (Type2): [Description...]
        opt_arg3 (Type3, optional): [What happens if omitted, what is default, units]

    Returns:
        ReturnType: [Describe returned value and its structure, especially keys for dicts or what list elements represent.]

    Example:
        result = tool_name(
            arg1="value1",
            arg2=some_int,
            opt_arg3=None
        )
        # result['some_key'] (describe what to look for)

    Notes:
        - [Any important caveats, required permissions, relevant links, 
           info about latency/side effects or cost.]
        - [If integration with external system: points of failure.]

    Raises:
        [Known/likely exceptions, especially those the user or LLM should handle.]  
    """
    # ... tool logic ...

Guide

1. Short summary — Purpose at a glance.
2. Context — When to use it, why, or for whom.
3. Arguments — Name, type, meaning, and edge cases.
4. Returns — Structure and meaning.
5. Example — Typical call and result.
6. Notes — Permissions, quotas, links, caveats.
7. Raises — Exceptions likely and their implications.

Development

• Write and register new tools for additional GCP operations.
• Use utils.logging.get_logger() for idiomatic logging in all modules.
• Keep tests, typing, and docs up to date.
• Before committing, run:
  • ruff format .
  • ruff check .
  • python -m compileall .

License

SPDX-License-Identifier: MIT