MCP Reference: cloudcli.googleapis.com

Cloud CLI MCP Server provides tools to run Cloud CLI commands in a remote sandbox environment.

A Model Context Protocol (MCP) server acts as a proxy between an external service that provides context, data, or capabilities to a Large Language Model (LLM) or AI application. MCP servers connect AI applications to external systems such as databases and web services, translating their responses into a format that the AI application can understand.

Server Setup

You must enable MCP servers and set up authentication before use. For more information about using Google and Google Cloud remote MCP servers, see Google Cloud MCP servers overview.

Server Endpoints

An MCP service endpoint is the network address and communication interface (usually a URL) of the MCP server that an AI application (the Host for the MCP client) uses to establish a secure, standardized connection. It is the point of contact for the LLM to request context, call a tool, or access a resource. Google MCP endpoints can be global or regional.

The Cloud CLI Execution API MCP server has the following global MCP endpoint:

  • https://cloudcli.googleapis.com/mcp

MCP Tools

An MCP tool is a function or executable capability that an MCP server exposes to a LLM or AI application to perform an action in the real world.

Tools

The cloudcli.googleapis.com MCP server has the following tool:

MCP Tools
run_gcloud_command

Executes a single gcloud CLI command within the user's Google Cloud project. CRITICAL SAFETY WARNING (POTENTIALLY DESTRUCTIVE): This tool can create, update, or delete GCP resources (e.g., gcloud compute instances delete). It is NOT restricted to read-only commands. Use extreme caution. FORBIDDEN COMMANDS: An agent MUST NOT execute the following gcloud commands (including their alpha/beta variants): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey. STRICT EXECUTION RULES:

  1. You MUST provide the 'project' parameter (i.e. project="projects/PROJECT_ID") when using this tool (it is used for Cloud CLI Execution API enablement check, billing, quota, etc.). This is NOT the same as the --project flag in gcloud commands used to specify the project gcloud operates on.
  2. Flag Formatting: You MUST always use an '=' sign to separate flag keys from their values for all long options. Correct: --zone=us-central1-a or --project=my-project. Incorrect: --zone us-central1-a or --project my-project.
  3. Billing Project: You cannot assume any pre-configured project or billing settings in the execution environment. For non-project scoped commands (e.g., folder or organization level) or specific scenarios like Cloud Storage Requester Pays, you MUST pass the --billing-project=PROJECT flag. For project-scoped commands, you MAY additionally specify --billing-project=PROJECT to override the quota project, which will take effect for GCP APIs that do not support resource-project-override.
  4. Project Scope: You SHOULD ALWAYS pass the --project=PROJECT_ID flag for project-scoped commands. Do not use it for organization or folder-level commands. If you do not provide a --project flag for a project-scoped command, the resource project will default to the project set in the --billing-project flag.
  5. If specifying --billing-project flag in the gcloud command, ensure that the value is a project ID or a project number. The value MUST NOT be a special value (ie LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. At least one of --project or --billing-project MUST be specified in the command string.
  7. Asynchronous Operations: For long-running synchronous operations (e.g., creating a VM or a database), you SHOULD ALWAYS pass the --async flag to prevent agent timeouts.
  8. Log Rate Limiting: When using gcloud logging read, you MUST ALWAYS include a --limit flag (e.g., --limit=100) to prevent credential and connection timeouts.
  9. Self-Correction: If a command returns an error, analyze the stderr, correct the syntax or flags, and retry in the next iteration.
  10. input_files: (Optional) A list of files to be created in the environment before running the command. Each file must have a 'path' (relative to the current directory) and 'contents'. The 'contents' must be plain text representing the file's content. This is useful for commands that read from files (e.g. gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Example gcloud commands/patterns:

  1. Read GCE instance logs with severity>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Note the use of quotes for the filter expression.
  2. List all PSC endpoints: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Describe a PSC endpoint: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Note the use of '=' for the --region flag.
  4. List all clusters: gcloud container clusters list --project=PROJECT_ID
  5. Describe a cluster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. List compute instances: gcloud compute instances list --project=PROJECT_ID
  7. Get IAM policy for a project: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

Response strings are formatted for terminal output by default (stdout or stderr). Use --format flag to change the format.

Get MCP tool specifications

To get the MCP tool specifications for all tools in an MCP server, use the tools/list method. The following example demonstrates how to use curl to list all tools and their specifications currently available within the MCP server.

Curl Request 
                      
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'