JUHE API Marketplace
andyl25 avatar
MCP Server

Google Cloud MCP Server

An MCP server that enables querying and interacting with Google Cloud services including Logging, Spanner, Monitoring, and Cloud Trace through natural language.

1
GitHub Stars
8/23/2025
Last Updated
No Configuration
Please check the documentation below.

README Documentation

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.

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source