gcp-storage

The gcp-storage-mcp is a FastAPI-based MCP server that provides a comprehensive REST API for Google Cloud Storage operations, including buckets, blobs, batch operations, signed URLs, and analytics. It ships with security features like API key authentication, rate limiting, and structured logging, and exposes health, metrics, and OpenAPI documentation for easy integration. To use it, deploy the MCP server via the uvx-based workflow (as shown in the configuration), then interact with the exposed endpoints using your API key. Typical interactions include listing buckets, creating buckets, uploading and downloading blobs, generating signed URLs, and performing batch operations. The API supports project management, blob search and filtering, and storage analytics, all accessible through intuitive endpoints such as /buckets, /buckets/{bucket_name}/blobs, /health, and /metrics. When integrating with client tooling like Claude Desktop or Cursor, point the client to the MCP URL and supply your API key for authentication.

You can explore core endpoints such as GET /buckets to list buckets, POST /buckets/{bucket_name} to create a bucket, and POST /buckets/{bucket_name}/blobs/{blob_name}/upload to upload a file. For secure access, you can request signed URLs via POST /buckets/{bucket_name}/blobs/{blob_name}/signed-url and retrieve public URLs with GET /buckets/{bucket_name}/blobs/{blob_name}/url. The API also supports health checks and metrics at /health and /metrics for observability. The included examples in the repository demonstrate common tasks like listing buckets, uploading files, and generating signed URLs using API keys for authentication.

Prerequisites:

• Python 3.11+
• Git
• Google Cloud SDK (optional for authentication) or a service account key for GCS access

Installation steps:

1. Clone the repository and navigate into it

git clone https://github.com/uysalserkan/gcp-storage-mcp.git
cd gcp-storage-mcp

2. (Recommended) Create and activate a Python virtual environment

python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows
# venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure Google Cloud credentials (one of the following):

• Service Account Key:

export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"

• Application Default Credentials:

gcloud auth application-default login

5. Run the server (example)

# Development mode
python gcp-storage-mcp/api.py

# Production mode with environment configuration (example)
GCP_STORAGE_API_LOG_LEVEL=INFO python gcp-storage-mcp/api.py

6. Access the API Documentation and Endpoints:

• Docs: http://localhost:8000/docs
• Health: http://localhost:8000/health
• Metrics: http://localhost:8000/metrics

Optional: If you want to run via the MCP orchestration tool (Claude Cursor/desktop), ensure you provide the appropriate mcp_config as shown in the configuration section.

Tips and common considerations:

• Ensure you provide a valid Google Cloud credential path or configure ADC properly to authenticate against Cloud Storage.
• Set GCP_STORAGE_API_LOG_LEVEL to control log verbosity in production.
• When using API keys, securely share the key with clients and rotate keys periodically.
• If you enable Redis-backed rate limiting, configure Redis connection details in your environment as required by the app.
• For large batch operations, consider enabling in-memory caching and tuning request limits to align with your workload.
• The mcp_config example uses uvx for Python-based MCPs; if you switch to another deployment method, adjust the command/args accordingly.
• Review health and metrics endpoints for observability in production and integrate with your monitoring stack.