Google Cloud MCP Server

A Model Context Protocol server that connects to Google Cloud services to provide context and tools for interacting with your Google Cloud resources.

Services

Supported Google Cloud services:

• [x] Billing
• [x] Error Reporting
• [x] Identity and Access Management (IAM)
• [x] Logging
• [x] Monitoring
• [x] Profiler
• [x] Spanner
• [x] Trace

Billing

Manage and analyse Google Cloud billing with cost optimisation insights:

Tools: gcp-billing-list-accounts, gcp-billing-get-account-details, gcp-billing-list-projects, gcp-billing-get-project-info, gcp-billing-list-services, gcp-billing-list-skus, gcp-billing-analyse-costs, gcp-billing-detect-anomalies, gcp-billing-cost-recommendations, gcp-billing-service-breakdown

Example prompts:

• "Show me all my billing accounts"
• "Analyse costs for project my-app-prod-123 for the last 30 days"
• "Generate cost recommendations for billing account billingAccounts/123456-789ABC-DEF012"
• "Check for billing anomalies in project my-ecommerce-456"

Error Reporting

Monitor and analyse application errors with automated investigation and remediation suggestions:

Tools: gcp-error-reporting-list-groups, gcp-error-reporting-get-group-details, gcp-error-reporting-analyse-trends

Example prompts:

• "Show me error groups from project my-webapp-prod-789 for the last hour"
• "Get details for error group projects/my-app-123/groups/xyz789"
• "Analyse error trends for service my-api in project analytics-prod-456"

IAM

Query and analyse IAM policies and permissions:

Tools: gcp-iam-get-project-policy, gcp-iam-test-project-permissions, gcp-iam-test-resource-permissions, gcp-iam-validate-deployment-permissions, gcp-iam-list-deployment-services, gcp-iam-analyse-permission-gaps

Example prompts:

• "Get IAM policy for project my-webapp-prod-123"
• "Test if I have storage.buckets.create permission on project data-lake-456"
• "Check deployment permissions for Cloud Run in project microservices-789"
• "Analyse permission gaps for deploying to GKE cluster in project k8s-prod-321"

Logging

Query and filter log entries from Google Cloud Logging:

Tools: gcp-logging-query-logs, gcp-logging-query-time-range, gcp-logging-search-comprehensive

Example prompts:

• "Show me logs from project my-app-prod-123 from the last hour with severity ERROR"
• "Search for logs containing 'timeout' from service my-api in project backend-456"
• "Query logs for resource type gce_instance in project compute-prod-789"

Spanner

Interact with Google Cloud Spanner databases:

Tools: gcp-spanner-execute-query, gcp-spanner-list-tables, gcp-spanner-list-instances, gcp-spanner-list-databases, gcp-spanner-query-natural-language, gcp-spanner-query-count

Example prompts:

• "List all databases in Spanner instance my-instance in project ecommerce-prod-123"
• "Execute SQL: SELECT COUNT(*) FROM users in database user-db in project my-app-456"
• "Show me table structure for orders in database inventory-db in project retail-789"

Monitoring

Retrieve and analyse metrics from Google Cloud Monitoring:

Tools: gcp-monitoring-query-metrics, gcp-monitoring-list-metric-types, gcp-monitoring-query-natural-language

Example prompts:

• "Show me CPU utilisation metrics for project web-app-prod-123 for the last 6 hours"
• "List available metric types for Compute Engine in project infrastructure-456"
• "Query memory usage for instances in project backend-services-789"

Profiler

Analyse application performance with Google Cloud Profiler:

Tools: gcp-profiler-list-profiles, gcp-profiler-analyse-performance, gcp-profiler-compare-trends

Example prompts:

• "List CPU profiles from project my-java-app-123 for the last 24 hours"
• "Analyse performance bottlenecks in service my-api in project backend-prod-456"
• "Compare heap profiles for deployment v1.2 vs v1.3 in project performance-test-789"

Trace

Analyse distributed traces from Google Cloud Trace:

Tools: gcp-trace-get-trace, gcp-trace-list-traces, gcp-trace-find-from-logs, gcp-trace-query-natural-language

Example prompts:

• "Get trace details for ID abc123def456 in project distributed-app-789"
• "Show me failed traces from project microservices-prod-123 from the last hour"
• "Find logs related to trace xyz789 in project web-backend-456"
• "Query traces for service checkout-api in project ecommerce-prod-321"

Compute

Manage Compute Engine VM instances and deploy simple static HTML websites using startup scripts.

Tools: gcp-compute-list-instances, gcp-compute-create-instance, gcp-compute-delete-instance, gcp-compute-start-instance, gcp-compute-stop-instance, get-compute-vm-status, get-compute-vm-ip, deploy-static-html-site

Example prompts:

• "Deploy a static HTML site in project my-site-123 in zone us-central1-a using VM name site-vm and serve <h1>Hello</h1>; return the public URL."
• "Check VM status for site-vm in us-central1-a until it is RUNNING."
• "Get the public HTTP URL for site-vm in us-central1-a."

Note: The deploy-static-html-site tool creates an e2-micro Debian 12 VM with an external IP and an nginx-based startup script; the HTML content is embedded (base64-encoded) in the startup script and written to /var/www/html/index.html. This flow requires no SSH or file uploads.

Quick Start

Once configured, you can interact with Google Cloud services using natural language:

"What are my current billing costs for project my-webapp-prod-123?"
"Show me errors from project ecommerce-api-456 in the last hour"
"Check if I have permission to deploy to Cloud Run in project microservices-789"
"Find logs containing 'database timeout' from project backend-prod-321 yesterday"
"List Spanner databases in instance prod-db for project data-store-654"
"What's the CPU usage of Compute Engine instances in project infrastructure-987?"

Authentication

This server supports two methods of authentication with Google Cloud:

1. Service Account Key File (Recommended): Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account key file. This is the standard Google Cloud authentication method.

2. Environment Variables: Set GOOGLE_CLIENT_EMAIL and GOOGLE_PRIVATE_KEY environment variables directly. This is useful for environments where storing a key file is not practical.

The server will also use the GOOGLE_CLOUD_PROJECT environment variable if set, otherwise it will attempt to determine the project ID from the authentication credentials.

Installation

# Clone the repository
git clone https://github.com/iamishaan24/gcp-mcp-server.git
cd google-cloud-mcp

# Install dependencies
pnpm install

# Build
pnpm build

Authenticate to Google Cloud:

gcloud auth application-default login

To create service account key:

gcloud config set project YOUR_PROJECT_ID

gcloud iam service-accounts create mcp-service-account \
  --display-name="MCP Service Account"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:mcp-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/viewer"

gcloud iam service-accounts keys create mcp-key.json \
  --iam-account=mcp-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com

To use the key

Linux/mac

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/mcp-key.json"

powershell

$env:GOOGLE_APPLICATION_CREDENTIALS="D:\path\to\mcp-key.json"

Configuration

Configure the mcpServers in your client:

{
  "mcpServers": {
      "google-cloud-mcp": {
          "command": "node",
          "args": [
              "/Users/foo/code/google-cloud-mcp/dist/index.js"
          ],
          "env": {
              "GOOGLE_APPLICATION_CREDENTIALS": "/Users/foo/.config/gcloud/application_default_credentials.json"
          }
      }
  }
}

Development

Starting the server

# Build the project
pnpm build

# Start the server
pnpm start

Development mode

# Build the project
pnpm build

# Start the server and inspector
npx -y @modelcontextprotocol/inspector node dist/index.js

Troubleshooting

Server Timeout Issues

If you encounter timeout issues when running the server with Smithery, try the following:

1. Enable debug logging by setting debug: true in your configuration
2. Ensure lazyAuth: true is set to defer authentication until it's actually needed
3. Ensure your credentials file is accessible and valid
4. Check the logs for any error messages

Important: Authentication is still required for operation, but with lazy loading enabled, the server will start immediately and authenticate when needed rather than during initialization.

Authentication Issues

The server supports two methods of authentication:

1. Service Account Key File: Set GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account key file
2. Environment Variables: Set GOOGLE_CLIENT_EMAIL and GOOGLE_PRIVATE_KEY environment variables

If you're having authentication issues, make sure:

• Your service account has the necessary permissions
• The key file is properly formatted and accessible
• Environment variables are correctly set