DOCSEARCHbyAlgolia
Submit Docs

gcloud-mcp

repository·main·Indexed 21 days ago

https://github.com/googleapis/gcloud-mcp

Model Context Protocol (MCP) servers that enable AI assistants to interact with Google Cloud services using natural language. The repository includes servers for the gcloud CLI (@google-cloud/gcloud-mcp), Cloud Observability (@google-cloud/observability-mcp), Cloud Storage (@google-cloud/storage-mcp), and Backup and Disaster Recovery (@google-cloud/backupdr-mcp).

Tokens
31.5K
Snippets
100
Records
138
Agent score
73%

What's inside gcloud-mcp

  1. Overview of gcloud MCP Servers

    main

    The gcloud-mcp project provides Model Context Protocol (MCP) servers that allow AI assistants to interact with Google Cloud environments using the gcloud CLI. This enables natural language interaction with cloud resources, automation of complex workflows, and lowers the barrier to entry for cloud management.

    Available MCP servers in this repository include:

    MCP Server NameDescriptionPackage Name
    gcloudInteract with Google Cloud via the gcloud CLI using natural language prompts.@google-cloud/gcloud-mcp
    observabilityAccess Google Cloud Observability APIs to query logs, metrics, and traces.@google-cloud/observability-mcp
    storageInteract with Google Cloud Storage for bucket and object management.@google-cloud/storage-mcp
    backupdrInteract with Google Cloud Backup and Disaster Recovery.@google-cloud/backupdr-mcp

  2. Use GCS MCP tools for storage management

    main

    The GCS MCP extension provides tools to interact with Google Cloud Storage. You can use these tools to perform tasks such as:

    • Listing GCS buckets.
    • Identifying the largest object for a specific content type.
    • Analyzing storage metadata via Storage Insights (using the execute_insights_query, get_metadata_table_schema, and list_insights_configs tools).

  3. Understand MCP Permissions and Security

    main

    The permissions available to the gcloud MCP are identical to the permissions of your active gcloud account.

    To implement the principle of least privilege, you should:

    1. Use Service Account Impersonation: Authorize as a service account instead of a user account to limit the scope of access.
    2. Assign Limited IAM Roles: Assign the service account only the specific roles required for the intended tasks.

    Command Restrictions: By default, the gcloud MCP prevents the execution of certain gcloud commands that are unsuitable for AI agents (such as those that require arbitrary inputs or initiate interactive sessions) to prevent security risks.

  4. How to handle Storage Insights intents with Gemini CLI

    main

    When using the GCS MCP extension, queries focused on analyzing Google Cloud Storage configuration metadata (e.g., cost optimization, security auditing, or data governance) are classified as Storage Insights Intent.

    Examples of such intents include:

    • "What is the total size of my storage?"
    • "Which bucket has the most objects?"
    • "Show the distribution of my storage classes."

    To fulfill these requests, the agent follows a specific workflow:

    1. Identify Configuration: Ask the user for the config_name and config_location of the dataset configuration if not provided.
    2. Retrieve Schema: Call get_metadata_table_schema using the configuration name and location to obtain the table schema and hints. If the configuration is incorrect, use list_insights_configs to help the user find the right one.
    3. Execute Query: Use the retrieved schema to draft and execute BigQuery SQL queries via the execute_insights_query tool.
    4. Respond: Answer the user's question based on the query results.

    Crucial Rule for SQL Construction: All BigQuery table references must be fully qualified using the format project_id.dataset_id.table_id (e.g., my-gcp-project.my_dataset.my_table).

  5. Handle long-running operations and polling

    main

    When a tool returns an Operation object, follow these interaction patterns:

    • Acknowledge: Inform the user that the task is in progress and provide the Operation ID.
    • Wait Times: Suggest the user wait at least 30 to 60 seconds before attempting to poll the status.
    • Polling Frequency: Do not suggest or initiate status checks more frequently than once per minute.

    Example Response: "The operation has started (ID: 12345). Please allow about a minute for processing before checking the status again."

  6. Set up the Google Cloud Observability MCP Server

    main

    The Google Cloud Observability MCP Server acts as a bridge between Model Context Protocol (MCP) clients (like the Gemini CLI) and Google Cloud Observability APIs. It allows you to use natural language to search for logs, view metrics, retrieve traces, and view error reports.

    To use this server, you must complete the authentication steps for both your user account and the application's credentials.

    # 1. Authenticate your user account
gcloud auth login

# 2. Set up Application Default Credentials (ADC) for the server
gcloud auth application-default login

  7. Configure gcloud MCP command allowlisting and denylisting

    main

    You can regulate which gcloud commands an AI agent is permitted to execute by providing a JSON configuration file. This file controls access via an allow list or a deny list.

    Important Rules:

    • The configuration file can contain either an allow key or a deny key, but not both.
    • A Default Denylist of unsafe commands is always enforced and cannot be overridden.
    • The path to the configuration file must be an absolute path.
    • The configuration is applied via the -c or --config command-line flag.

    Enforcement Logic:

    • Allowlisting: Only allows the specific command or release track specified. For example, allowing beta storage does not grant access to alpha storage or GA storage commands.
    • Denylisting:
      • Denylisting a GA command (e.g., compute instances delete) denies all its release tracks (alpha, beta, and GA).
      • Denylisting a pre-GA track (e.g., alpha) denies only that specific track.
    • Scope: Entries can be command groups (e.g., compute) or full commands (e.g., compute instances delete).
    {
  "allow": ["compute instances"]
}

  8. Set up gcloud-mcp for local development

    main

    To develop on the gcloud-mcp project locally, clone the repository, install dependencies, and link the specific MCP server package to make its binary available globally. You will also need the @google/gemini-cli installed.

    Follow these steps:

    1. Clone the repository and enter the directory.
    2. Run npm install at the root.
    3. Navigate to the specific server package (e.g., packages/gcloud-mcp).
    4. Run npm link to make the command available globally.
    5. Install the Gemini CLI globally if you haven't already.
    git clone https://github.com/googleapis/gcloud-mcp.git
cd gcloud-mcp
npm install
cd packages/gcloud-mcp
npm link
npm install -g @google/gemini-cli

  9. Initialize gcloud-mcp with Gemini CLI

    main

    Use the gcloud-mcp init command to configure your MCP client (like Gemini CLI) to use the gcloud-mcp server.

    Use the --local flag to control whether the client points to a local development installation or the remote npm registry:

    • Without --local: The configuration uses npx @google-cloud/gcloud-mcp, which pulls from the remote npm registry (unless the init command is executed from within the local repository directory).
    • With --local: The configuration uses npx gcloud-mcp, which points to your local npm installation. This is required if you want changes made in your local development directory to be reflected in the client.
    npx gcloud-mcp init --agent=gemini-cli --local

  10. Configure MCP servers for other AI clients

    main

    To use these MCP servers in other AI clients, add a configuration snippet to the client's JSON settings file. The general pattern for any server is:

    "[SERVER_NAME]": {
  "command": "npx",
  "args": ["-y", "@google-cloud/[PACKAGE_NAME]"]
}

    Client-specific configuration locations:

    • Claude Desktop: Edit claude_desktop_config.json via Claude > Settings > Developer > Edit Config.
    • Cline: Edit cline_mcp_settings.json via the MCP Servers icon > Configure MCP Servers.
    • Cursor: Edit .cursor/mcp.json (project-specific) or ~/.cursor/mcp.json (global).
    • Gemini CLI (Manual): Edit .gemini/settings.json (project-specific) or ~/.gemini/settings.json (global).
    • Visual Studio Code: Edit .vscode/mcp.json (project-specific) or your global user settings file.
    "gcloud": {
  "command": "npx",
  "args": ["-y", "@google-cloud/gcloud-mcp"]
}

  11. Identify the protection status of resources

    main

    To determine which resources are currently protected, follow these steps:

    1. List Resources: Use the find_protectable_resources tool to get a list of all protectable resources.
    2. Identify Locations: Extract the unique locations (regions or zones) from that list.
    3. Check Associations: For each unique location, call the list_backup_plan_associations tool.

    Definition of 'Protected':

    • A resource is protected if a backup plan association exists for it and its state is 'ACTIVE'.
    • A DISK is also considered protected if its associated VM is protected by a VM backup plan.

  12. Configure the gcloud MCP command path in settings.json

    main

    To use a custom allowlist or denylist, you must pass the absolute path to your JSON configuration file using the -c or --config flag within the gcloud configuration block of your AI client's settings (e.g., settings.json or ~/.gemini/extensions/gcloud/gemini-extension.json).

    {
  "gcloud": {
    "command": "npx",
    "args": [
      "-y",
      "@google-cloud/gcloud-mcp",
      "-c",
      "/abs/path/to/config.json"
    ]
  }
}