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 fileGOOGLE_CLOUD_PROJECT
: Your default Google Cloud project IDGOOGLE_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 loggingMCP_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:
-
Service Account Key File (Recommended):
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
-
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"
-
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 Logsgcp-logging-list-entries
: List log entries with filters
Spanner Tools
gcp-spanner-execute-query
: Execute SQL queries on Spanner databasesgcp-spanner-list-databases
: List Spanner databasesgcp-spanner-list-instances
: List Spanner instancesgcp-spanner-get-schema
: Get database schema informationgcp-spanner-query-count
: Get query execution metrics
Monitoring Tools
gcp-monitoring-query
: Query monitoring metricsgcp-monitoring-list-metrics
: List available metric descriptorsgcp-monitoring-get-resource-metrics
: Get metrics for specific resources
Trace Tools
get-trace
: Retrieve trace data by trace IDsearch-traces
: Search for traces with filtersget-trace-summary
: Get summary statistics for traces
Project Tools
gcp-get-project-info
: Get current project informationgcp-list-enabled-services
: List enabled APIs and services
Available Resources
Logging Resources
gcp://logging/logs/{logName}
: Individual log resourcesgcp://logging/entries
: Recent log entries
Spanner Resources
gcp://spanner/instances
: List of Spanner instancesgcp://spanner/databases/{instanceId}
: Databases in an instancegcp://spanner/schema/{instanceId}/{databaseId}
: Database schema
Monitoring Resources
gcp://monitoring/metrics
: Available monitoring metricsgcp://monitoring/resources
: Monitored resource types
Trace Resources
gcp://trace/traces
: Recent trace data
Available Prompts
analyze-logs
: Analyze log patterns and errorsquery-optimization
: Optimize Spanner queriestroubleshoot-performance
: Troubleshoot application performance issuessecurity-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
-
Check your credentials:
gcloud auth application-default login
-
Verify service account permissions:
- Logging Viewer
- Spanner Database User
- Monitoring Viewer
- Cloud Trace User
-
Test authentication:
DEBUG=true pnpm start
HTTP Transport Issues
-
Port conflicts: If port 3000 is in use, specify a different port:
MCP_HTTP_PORT=8080 MCP_TRANSPORT=http pnpm start
-
CORS issues: The server only accepts requests from localhost, 127.0.0.1, and .local domains for security.
-
Session management: Make sure to include the
Mcp-Session-Id
header in requests after initialization.
Performance Issues
-
Enable lazy authentication:
LAZY_AUTH=true pnpm start
-
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.