takashabe/gcp-o11y-mcp

GCP Observability MCP Server

Model Context Protocol (MCP) server for Google Cloud Platform Observability

Overview

This project provides an MCP server that offers access to Google Cloud Logging services. It enables AI assistants to read and search log entries from Google Cloud Logging through multiple transport protocols including stdio and Streamable HTTP.

Supported Transports

• stdio: Standard input/output communication (default)
• streamable-http: HTTP-based transport (future implementation)

Features

Available Tools

• list_log_entries: List log entries with optional filtering capabilities
• search_logs: Advanced log search using text queries and filters
• preset_query: Efficient log search with predefined optimized queries

Performance Optimizations

• Quota optimization: Reduced API usage through page size limits and caching
• Rate limiting: Automatic retry with exponential backoff
• In-memory cache: Prevents duplicate queries (2-10 minute cache duration)
• Efficient filtering: Server-side filtering reduces data transfer

Prerequisites

• Go 1.24.4+
• Google Cloud Project with Logging API enabled
• Service Account with appropriate permissions:
  • logging.entries.list
  • logging.logEntries.list

Environment Variables

• GOOGLE_CLOUD_PROJECT: Your Google Cloud Project ID (required)

Installation

1. Clone the repository

git clone https://github.com/takashabe/gcp-o11y-mcp.git
cd gcp-o11y-mcp

2. Set up Google Cloud authentication

gcloud auth application-default login

3. Install dependencies

task tidy

4. Build the server

go build -o bin/mcp-server ./cmd/mcp-server

5. MCP Configuration

Using Built Binary

Create .mcp.json in the project directory:

{
  "name": "gcp-o11y",
  "description": "Google Cloud Observability MCP Server",
  "command": "./bin/mcp-server",
  "args": ["-transport", "stdio"],
  "env": {
    "GOOGLE_CLOUD_PROJECT": "your-project-id"
  }
}

Using go run

For development or if you prefer to run without building:

{
  "name": "gcp-o11y",
  "description": "Google Cloud Observability MCP Server",
  "command": "go",
  "args": ["run", "./cmd/mcp-server", "-transport", "stdio"],
  "env": {
    "GOOGLE_CLOUD_PROJECT": "your-project-id"
  }
}

6. Restart Claude Code

After configuration, restart Claude Code to load the MCP server.

Usage

Using with Claude Code

Once the MCP server is configured and Claude Code is restarted, you can interact with Google Cloud Logging using natural language:

• "Show me the latest error logs"
• "Search for logs containing 'timeout' in the last hour"
• "Display all ERROR severity logs from today"
• "Find logs with authentication failure messages"

Preset Queries

For efficient searching, the following preset queries are available:

• cloud_run_errors: Recent errors from Cloud Run services
• cloud_run_service_errors: Errors for specific Cloud Run service
• recent_logs: Logs from the last hour
• high_severity: Critical and error logs from the last 6 hours

Development & Testing

Available Tasks

# List available tasks
task

# Run tests
task test

# Format code
task fmt

# Tidy dependencies
task tidy

Manual Testing

# Start stdio server
export GOOGLE_CLOUD_PROJECT=your-project-id
./bin/mcp-server -transport stdio

# Start HTTP server (when implemented)
./bin/mcp-server -transport streamable-http -addr :8080

# Test JSON-RPC communication
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./bin/mcp-server

Cloud Run Deployment

Deploy using configuration file

# Update PROJECT_ID in cloudrun.yaml
sed -i 's/PROJECT_ID/your-actual-project-id/g' cloudrun.yaml

# Deploy
gcloud run services replace cloudrun.yaml --region us-central1

Authentication

The server uses Google Cloud default credentials. For local development, run:

gcloud auth application-default login

Project Structure

.
├── cmd/mcp-server/       # Main server executable
├── internal/
│   ├── logging/          # Log processing logic
│   │   ├── client.go     # Google Cloud Logging client
│   │   ├── cache.go      # In-memory cache
│   │   ├── ratelimit.go  # Rate limiting
│   │   └── *.go          # Tool implementations
│   ├── server/           # MCP server implementation
│   └── transport/        # Transport layer abstraction
├── pkg/types/            # Type definitions
├── Taskfile.yml         # Task definitions
└── cloudrun.yaml        # Cloud Run configuration

License

This project is licensed under the MIT License - see the LICENSE file for details.