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

# Clone the repository
git clone <repository-url>
cd google-cloud-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

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)

# Start with stdio transport
pnpm start

# Or explicitly specify stdio
MCP_TRANSPORT=stdio pnpm start

Using HTTP Transport

# Start with HTTP transport
MCP_TRANSPORT=http pnpm start

# Or with custom port
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 pnpm start

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

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

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

Make Requests with Session

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Server-Sent Events Stream

curl -X GET http://127.0.0.1:3000/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: <session-id>"

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

# Install dependencies
pnpm install

# Run in development mode with stdio transport
pnpm dev

# Run in development mode with HTTP transport
MCP_TRANSPORT=http pnpm dev

# Build the project
pnpm build

# Run tests
pnpm test

# Lint the code
pnpm lint

# Format the code
pnpm format

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.