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)

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. 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

<details> <summary>BigQuery Tools</summary>

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"
}

</details>

<details> <summary>Cloud Logging Tools</summary>

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"
}

</details>

<details> <summary>>Cloud Storage Tools</summary>

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}
}

</details>

<details> <summary>Compute Engine Tools</summary>

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"
}

</details>

🖥️ 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:

1. Project ID: Replace your-project-id with your actual Google Cloud Project ID
2. Service Account: Replace /path/to/your/service-account-key.json with the path to your service account JSON file
3. 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

1. Consistent Return Types: All methods return dictionaries for easy JSON serialization
2. Flexible Authentication: Support for both service account files and default credentials
3. Comprehensive Error Handling: Specific exception handling for different GCP error types
4. Extensive Logging: Detailed logging throughout for debugging and monitoring
5. 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.