# 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](https://cloud.google.com/billing)
- [x] [Error Reporting](https://cloud.google.com/error-reporting)
- [x] [Identity and Access Management (IAM)](https://cloud.google.com/iam)
- [x] [Logging](https://cloud.google.com/logging)
- [x] [Monitoring](https://cloud.google.com/monitoring)
- [x] [Profiler](https://cloud.google.com/profiler)
- [x] [Spanner](https://cloud.google.com/spanner)
- [x] [Trace](https://cloud.google.com/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

```bash
# 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:

```bash
gcloud auth application-default login
```
To create service account key:

```bash
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:

```json
{
  "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

```bash
# Build the project
pnpm build

# Start the server
pnpm start
```

### Development mode

```bash
# 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