Google Cloud MCP Server

Google Cloud MCP Server

A Model Context Protocol (MCP) server for Google Cloud services including Logging, Spanner, Monitoring, and Cloud Trace.

Features

• Google Cloud Logging: Query logs, list log entries, and search across different log sources
• Google Cloud Spanner: Execute queries, list databases and instances, get schema information
• Google Cloud Monitoring: Query metrics, list metric descriptors, get monitoring data
• Google Cloud Trace: Retrieve trace data and analyze distributed system performance
• Resource Discovery: Automatically discover and list available Google Cloud resources
• Project Management: Tools for managing Google Cloud project settings

Transport Support

This server supports two transport modes:

1. Stdio Transport (Default)

The traditional MCP stdio transport for use with MCP clients like Claude Desktop.

2. HTTP Transport (New!)

A web-based HTTP transport implementing the MCP Streamable HTTP specification.

Installation

Configuration

Environment Variables

• GOOGLE_APPLICATION_CREDENTIALS: Path to your Google Cloud service account key file
• GOOGLE_CLOUD_PROJECT: Your default Google Cloud project ID
• GOOGLE_CLIENT_EMAIL: Service account email (alternative to credentials file)
• GOOGLE_PRIVATE_KEY: Service account private key (alternative to credentials file)
• LAZY_AUTH: Set to 'false' to initialize auth immediately (default: 'true')
• DEBUG: Set to 'true' for debug logging
• MCP_TRANSPORT: Transport type - 'stdio' (default) or 'http'
• MCP_HTTP_PORT: Port for HTTP transport (default: 3000)

Google Cloud Authentication

You can authenticate in several ways:

1. Service Account Key File (Recommended):
   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
2. Environment Variables:
   export GOOGLE_CLIENT_EMAIL=your-service-account@project.iam.gserviceaccount.com export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
3. Application Default Credentials: If running on Google Cloud, ADC will be used automatically.

Usage

Using Stdio Transport (Default)

Using HTTP Transport

When using HTTP transport, the server will be available at:

• MCP Endpoint: http://127.0.0.1:3000/mcp
• Health Check: http://127.0.0.1:3000/health

HTTP Transport Features

The HTTP transport implements the MCP Streamable HTTP specification with:

• Session Management: Automatic session ID assignment and tracking
• Server-Sent Events (SSE): For real-time communication and server-initiated messages
• Request/Response Handling: Proper JSON-RPC 2.0 message handling
• Security: Origin validation to prevent DNS rebinding attacks
• CORS Support: Cross-origin requests support for web applications
• Connection Management: Automatic cleanup of stale connections

HTTP Transport Usage Examples

Initialize Connection

The response will include a Mcp-Session-Id header that should be used in subsequent requests.

Make Requests with Session

Server-Sent Events Stream

Available Tools

Logging Tools

• gcp-logging-query: Query Google Cloud Logs
• gcp-logging-list-entries: List log entries with filters

Spanner Tools

• gcp-spanner-execute-query: Execute SQL queries on Spanner databases
• gcp-spanner-list-databases: List Spanner databases
• gcp-spanner-list-instances: List Spanner instances
• gcp-spanner-get-schema: Get database schema information
• gcp-spanner-query-count: Get query execution metrics

Monitoring Tools

• gcp-monitoring-query: Query monitoring metrics
• gcp-monitoring-list-metrics: List available metric descriptors
• gcp-monitoring-get-resource-metrics: Get metrics for specific resources

Trace Tools

• get-trace: Retrieve trace data by trace ID
• search-traces: Search for traces with filters
• get-trace-summary: Get summary statistics for traces

Project Tools

• gcp-get-project-info: Get current project information
• gcp-list-enabled-services: List enabled APIs and services

Available Resources

Logging Resources

• gcp://logging/logs/{logName}: Individual log resources
• gcp://logging/entries: Recent log entries

Spanner Resources

• gcp://spanner/instances: List of Spanner instances
• gcp://spanner/databases/{instanceId}: Databases in an instance
• gcp://spanner/schema/{instanceId}/{databaseId}: Database schema

Monitoring Resources

• gcp://monitoring/metrics: Available monitoring metrics
• gcp://monitoring/resources: Monitored resource types

Trace Resources

• gcp://trace/traces: Recent trace data

Available Prompts

• analyze-logs: Analyze log patterns and errors
• query-optimization: Optimize Spanner queries
• troubleshoot-performance: Troubleshoot application performance issues
• security-analysis: Analyze security-related logs and traces

Development

Troubleshooting

Authentication Issues

1. Check your credentials:
   gcloud auth application-default login
2. Verify service account permissions:
   • Logging Viewer
   • Spanner Database User
   • Monitoring Viewer
   • Cloud Trace User
3. Test authentication:
   DEBUG=true pnpm start

HTTP Transport Issues

1. Port conflicts: If port 3000 is in use, specify a different port:
   MCP_HTTP_PORT=8080 MCP_TRANSPORT=http pnpm start
2. CORS issues: The server only accepts requests from localhost, 127.0.0.1, and .local domains for security.
3. Session management: Make sure to include the Mcp-Session-Id header in requests after initialization.

Performance Issues

1. Enable lazy authentication:
   LAZY_AUTH=true pnpm start
2. Reduce logging verbosity: Remove DEBUG=true from production environments.

Security Considerations

HTTP Transport Security

• The server binds only to 127.0.0.1 (localhost) by default
• Origin header validation prevents DNS rebinding attacks
• Sessions are automatically cleaned up
• Request timeouts prevent resource exhaustion

Google Cloud Security

• Use service accounts with minimal required permissions
• Regularly rotate service account keys
• Monitor access logs for unusual activity
• Use VPC-native clusters when possible

License

MIT License - see LICENSE file for details.