Google Cloud MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Cloud Platform services. This project provides Python wrapper modules and MCP tools for managing various GCP services including BigQuery, Cloud Logging, Cloud Storage, and Compute Engine.

🚀 Features

BigQuery: Data warehouse operations including query execution, data loading/exporting, job management, and cost estimation
Cloud Logging: Comprehensive log management with reading/writing logs, bucket management, sinks, exclusions, and metrics
Cloud Storage: Complete bucket and object management with lifecycle policies and batch operations
Compute Engine: Virtual machine lifecycle management and zone operations
MCP Integration: Full MCP server implementation for AI model interactions
Flexible Authentication: Support for both service account files and default credentials

📦 Installation

From uv tool

uv tool install google-cloud-mcp

From Source

git clone https://github.com/lockon-n/google-cloud-mcp.git
cd google-cloud-mcp
pip install -e .

🔧 Setup

Authentication

Option 1: Service Account (Recommended)

Create a service account in Google Cloud Console
Download the JSON key file
Place it as service-account-key.json in your project root

Option 2: Default Credentials

gcloud auth application-default login

Running the MCP Server

uv run main.py

🛠️ Available Tools

BigQuery Tools

`google-cloud-bigquery_execute_query`

Execute SQL queries with optional cost estimation.

{
  "query": "SELECT * FROM dataset.table LIMIT 10",
  "dry_run": false,
  "max_results": 1000
}

`google-cloud-bigquery_create_dataset`

Create a new BigQuery dataset.

{
  "dataset_id": "my_dataset",
  "description": "My dataset description",
  "location": "US"
}

`google-cloud-bigquery_create_table`

Create a new table with schema.

{
  "dataset_id": "my_dataset",
  "table_id": "my_table",
  "schema": [
    {"name": "id", "type": "INTEGER", "mode": "REQUIRED"},
    {"name": "name", "type": "STRING", "mode": "NULLABLE"}
  ]
}

`google-cloud-bigquery_load_data_from_csv`

Load data from CSV file into BigQuery table.

{
  "dataset_id": "my_dataset",
  "table_id": "my_table",
  "csv_file_path": "/path/to/data.csv",
  "write_disposition": "WRITE_APPEND"
}

`google-cloud-bigquery_export_to_storage`

Export BigQuery table to Cloud Storage.

{
  "dataset_id": "my_dataset",
  "table_id": "my_table",
  "bucket_name": "my-bucket",
  "file_path": "exports/data.csv"
}

`google-cloud-bigquery_list_datasets`

List all datasets in the project.

`google-cloud-bigquery_list_tables`

List all tables in a dataset.

{
  "dataset_id": "my_dataset"
}

`google-cloud-bigquery_get_job_status`

Get the status of a BigQuery job.

{
  "job_id": "job_12345"
}

Cloud Logging Tools

`google-cloud-logging_write_log`

Write log entries (text or structured).

{
  "log_name": "my-application",
  "message": "Application started successfully",
  "severity": "INFO",
  "labels": {"component": "backend"}
}

`google-cloud-logging_read_logs`

Read and filter log entries.

{
  "filter_string": "severity>=ERROR",
  "max_results": 100,
  "time_range_hours": 24
}

`google-cloud-logging_list_logs`

List all log names in the project.

`google-cloud-logging_delete_log`

Delete all entries in a specific log.

{
  "log_name": "old-application"
}

`google-cloud-logging_create_log_bucket`

Create a new log bucket for retention management.

{
  "bucket_id": "my-log-bucket",
  "retention_days": 90,
  "description": "Application logs bucket",
  "locked": false
}

`google-cloud-logging_update_log_bucket`

Update log bucket configuration.

{
  "bucket_id": "my-log-bucket",
  "retention_days": 120,
  "description": "Updated description"
}

`google-cloud-logging_delete_log_bucket`

Delete a log bucket.

{
  "bucket_id": "my-log-bucket"
}

`google-cloud-logging_clear_log_bucket`

Clear all logs from a bucket while keeping the bucket.

{
  "bucket_id": "my-log-bucket"
}

`google-cloud-logging_list_log_buckets`

List all log buckets in the project.

`google-cloud-logging_create_log_sink`

Create a log sink for exporting logs.

{
  "sink_name": "my-sink",
  "destination": "storage.googleapis.com/my-export-bucket",
  "filter_string": "severity>=WARNING"
}

`google-cloud-logging_list_log_sinks`

List all log sinks in the project.

`google-cloud-logging_delete_log_sink`

Delete a log sink.

{
  "sink_name": "my-sink"
}

`google-cloud-logging_create_exclusion`

Create a log exclusion filter.

{
  "exclusion_name": "debug-exclusion",
  "filter_string": "severity<INFO"
}

`google-cloud-logging_list_exclusions`

List all log exclusions.

`google-cloud-logging_delete_exclusion`

Delete a log exclusion.

{
  "exclusion_name": "debug-exclusion"
}

`google-cloud-logging_search_logs`

Search logs with simplified parameters.

{
  "search_query": "error occurred",
  "time_range_hours": 12,
  "severity_levels": ["ERROR", "CRITICAL"]
}

`google-cloud-logging_export_logs_to_storage`

Create a sink to export logs to Cloud Storage.

{
  "sink_name": "storage-export",
  "bucket_name": "my-log-exports"
}

`google-cloud-logging_export_logs_to_bigquery`

Create a sink to export logs to BigQuery.

{
  "sink_name": "bigquery-export",
  "dataset_id": "log_analysis"
}

>Cloud Storage Tools

`google-cloud-storage_create_bucket`

Create a new Cloud Storage bucket.

{
  "bucket_name": "my-new-bucket",
  "location": "US",
  "storage_class": "STANDARD"
}

`google-cloud-storage_delete_bucket`

Delete a bucket.

{
  "bucket_name": "my-bucket"
}

`google-cloud-storage_list_buckets`

List all buckets in the project.

`google-cloud-storage_upload_file`

Upload a file to a bucket.

{
  "bucket_name": "my-bucket",
  "local_file_path": "/path/to/file.txt",
  "blob_name": "uploads/file.txt"
}

`google-cloud-storage_download_file`

Download a file from a bucket.

{
  "bucket_name": "my-bucket",
  "blob_name": "uploads/file.txt",
  "local_file_path": "/path/to/download/file.txt"
}

`google-cloud-storage_delete_file`

Delete a file from a bucket.

{
  "bucket_name": "my-bucket",
  "blob_name": "uploads/file.txt"
}

`google-cloud-storage_list_files`

List files in a bucket.

{
  "bucket_name": "my-bucket",
  "prefix": "uploads/",
  "max_results": 100
}

`google-cloud-storage_copy_file`

Copy a file within or between buckets.

{
  "source_bucket": "source-bucket",
  "source_blob": "file.txt",
  "destination_bucket": "dest-bucket",
  "destination_blob": "backup/file.txt"
}

`google-cloud-storage_move_file`

Move a file within or between buckets.

{
  "source_bucket": "source-bucket",
  "source_blob": "file.txt",
  "destination_bucket": "dest-bucket",
  "destination_blob": "moved/file.txt"
}

`google-cloud-storage_generate_signed_url`

Generate a signed URL for temporary access.

{
  "bucket_name": "my-bucket",
  "blob_name": "private/file.txt",
  "expiration_hours": 24,
  "method": "GET"
}

`google-cloud-storage_set_bucket_lifecycle`

Set lifecycle management policies.

{
  "bucket_name": "my-bucket",
  "rules": [
    {
      "action": "Delete",
      "conditions": {"age": 365}
    }
  ]
}

`google-cloud-storage_batch_upload`

Upload multiple files to a bucket.

{
  "bucket_name": "my-bucket",
  "file_mappings": [
    {
      "local_path": "/path/file1.txt",
      "blob_name": "uploads/file1.txt"
    }
  ]
}

`google-cloud-storage_batch_download`

Download multiple files from a bucket.

{
  "bucket_name": "my-bucket",
  "file_mappings": [
    {
      "blob_name": "uploads/file1.txt",
      "local_path": "/path/download/file1.txt"
    }
  ]
}

`google-cloud-storage_search_files`

Search for files using patterns.

{
  "bucket_name": "my-bucket",
  "name_pattern": "*.log",
  "size_range": {"min_bytes": 1024, "max_bytes": 1048576}
}

Compute Engine Tools

`google-cloud-compute_create_instance`

Create a new VM instance.

{
  "instance_name": "my-vm",
  "zone": "us-central1-a",
  "machine_type": "e2-medium",
  "image_family": "ubuntu-2004-lts",
  "image_project": "ubuntu-os-cloud"
}

`google-cloud-compute_delete_instance`

Delete a VM instance.

{
  "instance_name": "my-vm",
  "zone": "us-central1-a"
}

`google-cloud-compute_start_instance`

Start a stopped VM instance.

{
  "instance_name": "my-vm",
  "zone": "us-central1-a"
}

`google-cloud-compute_stop_instance`

Stop a running VM instance.

{
  "instance_name": "my-vm",
  "zone": "us-central1-a"
}

`google-cloud-compute_restart_instance`

Restart a VM instance.

{
  "instance_name": "my-vm",
  "zone": "us-central1-a"
}

`google-cloud-compute_list_instances`

List all VM instances in a zone.

{
  "zone": "us-central1-a"
}

`google-cloud-compute_get_instance`

Get detailed information about a VM instance.

{
  "instance_name": "my-vm",
  "zone": "us-central1-a"
}

`google-cloud-compute_list_zones`

List all available zones in the project.

`google-cloud-compute_get_operation_status`

Get the status of a Compute Engine operation.

{
  "operation_name": "operation-123456",
  "zone": "us-central1-a"
}

🖥️ Claude Desktop Configuration

Add the following configuration to your Claude Desktop MCP settings file:

{
  "mcpServers": {
    "google-cloud-mcp": {
      "command": "uvx",
      "args": [
        "google-cloud-mcp",
        "--project-id", "your-project-id",
        "--service-account-path", "/path/to/your/service-account-key.json"
        "--allowed-buckets", "bucket1,bucket2,bucket3",
        "--allowed-datasets", "dataset1,dataset2",
        "--allowed-log-buckets", "log-bucket1",
        "--allowed-instances", "vm1,vm2"
      ],
    }
  }
}

Configuration Notes:

Project ID: Replace your-project-id with your actual Google Cloud Project ID
Service Account: Replace /path/to/your/service-account-key.json with the path to your service account JSON file
Access Controls: Specify comma-separated lists of allowed resources to restrict access

🏗️ Architecture

The project follows a modular architecture with separate managers for each GCP service:

BigQuery (src/big_query.py): Data warehouse operations including query execution, data loading/exporting, job management, and cost estimation
Cloud Logging (src/cloud_logging.py): Log management operations including reading/writing logs, managing buckets, sinks, exclusions, and metrics
Cloud Storage (src/cloud_storage.py): Bucket and object management including CRUD operations, lifecycle management, and batch operations
Compute Engine (src/compute_engine.py): Virtual machine management including instance lifecycle operations and zone management

Each manager class follows a consistent pattern:

Constructor takes project_id and optional service_account_path
Methods return dictionaries with operation results
Comprehensive error handling and logging
Support for both service account and default credential authentication

🧪 Testing

Run the test server:

uv run test_server.py

This will test all available MCP tools and verify their functionality.

🔧 Development

Project Structure

google-cloud-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── big_query.py       # BigQuery manager
│   ├── cloud_logging.py   # Cloud Logging manager  
│   ├── cloud_storage.py   # Cloud Storage manager
│   └── compute_engine.py  # Compute Engine manager
├── main.py                # Entry point
├── test_server.py         # Test runner
├── pyproject.toml         # Package configuration
├── CLAUDE.md             # Development guidelines
└── README.md             # This file

Key Design Patterns

Consistent Return Types: All methods return dictionaries for easy JSON serialization
Flexible Authentication: Support for both service account files and default credentials
Comprehensive Error Handling: Specific exception handling for different GCP error types
Extensive Logging: Detailed logging throughout for debugging and monitoring
MCP Integration: Full compliance with MCP protocol specifications

📋 Requirements

Python 3.8+
Google Cloud SDK (optional, for default credentials)
Required Python packages (automatically installed):
- google-cloud-bigquery
- google-cloud-logging
- google-cloud-storage
- google-cloud-compute
- mcp

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Google Cloud Platform for comprehensive APIs
MCP (Model Context Protocol) for the integration framework
The Python community for excellent cloud libraries

Note: This project is designed to work seamlessly with AI models through the MCP protocol, providing a comprehensive interface for Google Cloud Platform operations.