gcp-storage-mcp

uysalserkan/gcp-storage-mcp

3.4

If you are the rightful owner of gcp-storage-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A comprehensive, enterprise-grade FastAPI server providing REST endpoints for Google Cloud Storage operations.

🚀 Professional GCP Storage API

A comprehensive, enterprise-grade FastAPI server providing REST endpoints for Google Cloud Storage operations. Built with production-ready features including authentication, rate limiting, monitoring, caching, and structured logging.

Logo

✨ Features

🔧 Core API Features

  • Complete GCS Operations: Full REST API for buckets, blobs, and storage management
  • Batch Operations: Efficient bulk upload/delete operations
  • Storage Analytics: Comprehensive storage usage and performance metrics
  • Search & Filter: Advanced blob search and size-based filtering
  • Signed URLs: Temporary access URL generation with configurable expiration
  • Project Management: Multi-project support and project switching

🔒 Security & Authentication

  • API Key Authentication: Secure API key-based authentication system
  • Rate Limiting: Configurable rate limiting with Redis support
  • CORS Protection: Configurable cross-origin resource sharing
  • Security Headers: Comprehensive security headers (CSP, HSTS, etc.)
  • Input Validation: Extensive request validation and sanitization

⚡ Performance & Monitoring

  • Intelligent Caching: In-memory caching with TTL and automatic invalidation
  • Request Tracking: Unique request IDs for complete request tracing
  • Metrics Collection: Built-in performance and usage metrics
  • Structured Logging: JSON-based structured logging with request context
  • Health Checks: Advanced health monitoring with dependency status

🛡️ Production Ready

  • Configuration Management: Environment-based configuration system
  • Error Handling: Comprehensive error responses with detailed context
  • Graceful Shutdown: Proper application lifecycle management
  • Documentation: Auto-generated OpenAPI documentation with examples
  • Monitoring Endpoints: Built-in metrics and health check endpoints

📖 Usage

GCP Storage MCP can be used with Claude Desktop, Cursor, and more.

📦 Claude Desktop

claude_desktop_config.json

"mcpServers": {
    "gcp-storage-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/uysalserkan/gcp-storage-mcp",
        "gcp-storage-mcp",
        "--credential_path",
        "your-credential-path.json"
      ]
    },
    ...
}

📦 Cursor

.cursor/mcp.json

"mcpServers": {
    "gcp-storage-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/uysalserkan/gcp-storage-mcp",
        "gcp-storage-mcp",
        "--credential_path",
        "your-credential-path.json"
      ]
    },
    ...
}

📦 Quick Start FastAPI

Prerequisites

  • Python 3.11+
  • Google Cloud SDK installed and configured
  • Active Google Cloud Project with Cloud Storage API enabled
  • Service Account with appropriate permissions

Installation

  1. Clone and Setup
git clone https://github.com/your-username/gcp-storage-mcp.git
cd gcp-storage-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
  1. Configure GCP Authentication
# Option 1: Service Account Key
export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"

# Option 2: Application Default Credentials
gcloud auth application-default login
  1. Start the Server
# Development mode
python gcp-storage-mcp/api.py

# Production mode with configuration
GCP_STORAGE_API_LOG_LEVEL=INFO python gcp-storage-mcp/api.py
  1. Access the API
  • API Documentation: http://localhost:8000/docs
  • Health Check: http://localhost:8000/health
  • Metrics: http://localhost:8000/metrics

📖 API Documentation

Core Endpoints

Health & Monitoring
  • GET /health - Advanced health check with dependencies
  • GET /metrics - System performance metrics
  • GET / - API information and navigation
Project Management
  • GET /projects - List all accessible GCP projects
  • GET /projects/current - Get current project ID
Bucket Operations
  • GET /buckets - List all buckets
  • POST /buckets/{bucket_name} - Create bucket
  • DELETE /buckets/{bucket_name} - Delete bucket
  • GET /buckets/{bucket_name} - Get bucket information
  • GET /buckets/{bucket_name}/exists - Check bucket existence
Blob Operations
  • GET /buckets/{bucket_name}/blobs - List blobs with prefix filtering
  • POST /buckets/{bucket_name}/blobs/{blob_name}/upload - Upload blob
  • POST /buckets/{bucket_name}/blobs/{blob_name}/download - Download blob
  • DELETE /buckets/{bucket_name}/blobs/{blob_name} - Delete blob
  • GET /buckets/{bucket_name}/blobs/{blob_name} - Get blob information
  • GET /buckets/{bucket_name}/blobs/{blob_name}/url - Get public URL
  • POST /buckets/{bucket_name}/blobs/{blob_name}/signed-url - Generate signed URL
Advanced Operations
  • POST /buckets/{bucket_name}/blobs/{blob_name}/copy - Copy blob
  • POST /buckets/{bucket_name}/blobs/{blob_name}/move - Move blob
  • POST /buckets/{bucket_name}/batch/upload - Batch upload
  • POST /buckets/{bucket_name}/batch/delete - Batch delete
Analytics & Search
  • GET /buckets/{bucket_name}/analytics/storage - Storage analytics
  • POST /buckets/{bucket_name}/search - Search blobs by pattern
  • POST /buckets/{bucket_name}/filter - Filter blobs by size

🔧 Usage Examples

Basic Operations

Authentication with API Key
curl -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     http://localhost:8000/health
List Buckets
curl -H "X-API-Key: your-api-key" \
     http://localhost:8000/buckets
Upload a File
curl -X POST \
     -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"file_path": "/path/to/local/file.txt"}' \
     http://localhost:8000/buckets/my-bucket/blobs/path/to/file.txt/upload
Generate Signed URL
curl -X POST \
     -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"expiration_hours": 24, "method": "GET"}' \
     http://localhost:8000/buckets/my-bucket/blobs/file.txt/signed-url

Python Client Example

import httpx
import asyncio

class GCPStorageClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url
        self.headers = {"X-API-Key": api_key}

    async def list_buckets(self):
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/buckets",
                headers=self.headers
            )
            return response.json()

    async def upload_file(self, bucket: str, blob_name: str, file_path: str):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/buckets/{bucket}/blobs/{blob_name}/upload",
                headers=self.headers,
                json={"file_path": file_path}
            )
            return response.json()

# Usage
async def main():
    client = GCPStorageClient("http://localhost:8000", "your-api-key")

    # List buckets
    buckets = await client.list_buckets()
    print(f"Found {buckets['count']} buckets")

    # Upload file
    result = await client.upload_file(
        "my-bucket",
        "documents/file.pdf",
        "/local/path/file.pdf"
    )
    print(f"Upload completed: {result}")

if __name__ == "__main__":
    asyncio.run(main())

📊 Monitoring & Observability

Health Monitoring

The API provides comprehensive health checks:

# Basic health check
curl http://localhost:8000/health

# Response includes:
# - Overall status
# - GCP connection status
# - Dependency health
# - Performance metrics
# - Uptime information

Metrics Collection

Built-in metrics endpoint provides:

curl http://localhost:8000/metrics

# Metrics include:
# - Request counts by endpoint
# - Response times
# - Error rates
# - Active requests
# - Cache hit rates

Structured Logging

All requests are logged with structured JSON:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "INFO",
  "message": "Request completed",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "GET",
  "path": "/buckets",
  "status_code": 200,
  "duration_ms": 45.2,
  "client_ip": "192.168.1.100"
}

🔒 Security Best Practices

Authentication

  • Use strong, randomly generated API keys
  • Rotate API keys regularly
  • Store keys securely (environment variables, secret managers)

CORS Configuration

# Restrict origins in production
GCP_STORAGE_API_ALLOWED_ORIGINS="https://yourdomain.com,https://app.yourdomain.com"

Rate Limiting

# Configure appropriate limits
GCP_STORAGE_API_RATE_LIMIT_DEFAULT="1000/hour"
GCP_STORAGE_API_RATE_LIMIT_STORAGE="redis://secure-redis:6379"

GCP Permissions

Minimum required IAM roles:

  • roles/storage.objectViewer - Read operations
  • roles/storage.objectCreator - Upload operations
  • roles/storage.admin - Full management (production)

📈 Performance Features

Intelligent Caching

  • Bucket Lists: Cached for 5 minutes
  • Bucket Info: Cached for 10 minutes
  • Blob URLs: Cached for 1 hour
  • Storage Analytics: Cached for 30 minutes
  • Automatic Invalidation: Cache cleared on data modifications

Request Optimization

  • Parallel Processing: Concurrent operations where possible
  • Batch Operations: Efficient bulk operations
  • Connection Pooling: Optimized GCP client connections
  • Request Tracking: Complete request lifecycle monitoring

🧪 Testing

# Install test dependencies
pip install pytest pytest-cov httpx

# Run tests
pytest tests/

# Run with coverage
pytest --cov=gcp-storage-mcp tests/

# Integration tests (requires GCP setup)
GCP_STORAGE_API_TEST_BUCKET="test-bucket" pytest tests/integration/

🤝 Contributing

We welcome contributions! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Follow the existing code style
  4. Add tests for new features
  5. Update documentation
  6. Submit a pull request

📄 License

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

🔗 Resources

📞 Support

Status: ✅ Production Ready | Version: 1.0.0 | Last Updated: January 2025