GCP MCP Server

# Quick Start Guide Get the GCP MCP Server running locally in 5 minutes and integrate it with Claude Code. ## ⚡ Super Quick Setup (One Command) **Just want to get started fast?** Use this single command approach: 1. **Clone and install**: ```bash git clone https://github.com/JayRajGoyal/gcp-mcp.git cd gcp-mcp ./install.sh ``` 2. **Get your GCP credentials file** (see instructions below) 3. **Add to Claude Code** (replace `/path/to/credentials.json` with your actual path): ```json { "mcpServers": { "gcp": { "command": "python", "args": [ "-m", "gcp_mcp.cli", "--credentials", "/path/to/your/credentials.json" ], "cwd": "/path/to/gcp-mcp" } } } ``` That's it! The server automatically extracts the project ID from your credentials file. ## 🚀 Detailed Setup ### Option 1: Docker (Recommended for Quick Testing) 1. **Clone and setup**: ```bash git clone https://github.com/JayRajGoyal/gcp-mcp.git cd gcp-mcp ``` 2. **Set up your GCP credentials**: ```bash # Copy the example environment file cp .env.example .env # Edit .env with your project ID nano .env ``` 3. **Get GCP service account key**: ```bash # Create a service account (replace YOUR_PROJECT_ID) gcloud iam service-accounts create gcp-mcp-dev \ --description="GCP MCP Server for local development" \ --display-name="GCP MCP Dev" # Add required permissions gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member="serviceAccount:gcp-mcp-dev@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/logging.viewer" gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member="serviceAccount:gcp-mcp-dev@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/monitoring.viewer" # Download the key gcloud iam service-accounts keys create ./gcp-mcp-credentials.json \ --iam-account=gcp-mcp-dev@YOUR_PROJECT_ID.iam.gserviceaccount.com ``` 4. **Update your .env file**: ```bash GCP_PROJECT=YOUR_PROJECT_ID GOOGLE_APPLICATION_CREDENTIALS=./gcp-mcp-credentials.json LOG_LEVEL=DEBUG ``` 5. **Run with Docker**: ```bash docker-compose up --build ``` The server will start on `stdio` (standard input/output) as required by MCP protocol. ### Option 2: Local Python Development 1. **Install Python dependencies**: ```bash # Create virtual environment python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt pip install -e . ``` 2. **Set up configuration**: ```bash # Copy local config cp config.local.json config.json # Edit with your project ID nano config.json ``` 3. **Set environment variables**: ```bash export GCP_PROJECT="YOUR_PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="./gcp-mcp-credentials.json" ``` 4. **Run the server**: ```bash # For local development python -m gcp_mcp.cli --local --debug # Or with specific config python -m gcp_mcp.cli --config config.json --project YOUR_PROJECT_ID --debug ``` ## 🔗 Integrate with Claude Code ### Step 1: Configure Claude Code Add this to your Claude Code MCP configuration file: **Location of config file:** - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/claude/claude_desktop_config.json` ### Step 2: Add MCP Server Configuration **Option A: Using Python directly** ```json { "mcpServers": { "gcp": { "command": "python", "args": ["-m", "gcp_mcp.cli", "--local", "--debug"], "cwd": "/path/to/gcp-mcp", "env": { "GCP_PROJECT": "YOUR_PROJECT_ID", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/gcp-mcp-credentials.json" } } } } ``` **Option B: Using Docker (if you prefer containers)** ```json { "mcpServers": { "gcp": { "command": "docker", "args": [ "run", "--rm", "-i", "--env-file", "/path/to/gcp-mcp/.env", "-v", "/path/to/gcp-mcp-credentials.json:/app/credentials.json:ro", "gcp-mcp:latest" ] } } } ``` ### Step 3: Restart Claude Code Restart Claude Code to load the new MCP server configuration. ## 🧪 Test the Integration Once Claude Code is restarted, you can test the integration: ### Basic Log Queries ``` "Show me recent errors from my GCP project" "Find logs containing 'database timeout' from the last hour" "Get the 10 most recent critical errors" ``` ### Advanced Queries ``` "Analyze error patterns in my Kubernetes cluster from the last 6 hours" "Search for authentication failures in the last 24 hours" "Show me performance issues across all services" ``` ### Enterprise Features (if you have multiple projects) ``` "Compare error rates between production and staging projects" "Analyze security events across all my GCP projects" "Generate a root cause analysis for recent outages" ``` ## 🛠️ Available Tools Once integrated, Claude Code will have access to these tools: ### Basic Logging Tools - `query_logs` - Query GCP logs with filters - `analyze_error_logs` - Analyze error patterns - `get_recent_errors` - Get latest errors - `search_logs_by_message` - Search by text content ### Enterprise Logging Tools - `advanced_log_query` - Multi-project advanced queries - `error_root_cause_analysis` - Comprehensive RCA - `security_log_analysis` - Security-focused analysis - `performance_log_analysis` - Performance troubleshooting - `log_pattern_discovery` - Pattern and anomaly detection - `cross_service_trace_analysis` - Distributed tracing ### Monitoring Tools - `get_metrics` - Basic metrics retrieval - `advanced_metrics_query` - Enterprise metrics analysis - `sla_slo_analysis` - SLA/SLO monitoring - `alert_policy_analysis` - Alert effectiveness analysis - `resource_optimization_analysis` - Cost and performance optimization - `infrastructure_health_check` - Comprehensive health checks ## 🔧 Troubleshooting ### Common Issues **1. "Authentication failed"** ```bash # Check if credentials file exists and is valid ls -la ./gcp-mcp-credentials.json gcloud auth activate-service-account --key-file=./gcp-mcp-credentials.json gcloud projects list ``` **2. "Project not found"** ```bash # Verify project ID gcloud config get-value project gcloud projects describe YOUR_PROJECT_ID ``` **3. "Permission denied"** ```bash # Check service account permissions gcloud projects get-iam-policy YOUR_PROJECT_ID \ --flatten="bindings[].members" \ --format="table(bindings.role)" \ --filter="bindings.members:gcp-mcp-dev@YOUR_PROJECT_ID.iam.gserviceaccount.com" ``` **4. Claude Code can't find the server** - Check that the path in `claude_desktop_config.json` is correct - Ensure Python virtual environment is activated if using direct Python - Try running the server manually first to test it works **5. Server starts but no tools available** - Check the logs for initialization errors - Verify GCP APIs are enabled in your project - Ensure service account has proper roles ### Enable Debug Logging Add `--debug` flag to see detailed logs: ```bash python -m gcp_mcp.cli --local --debug ``` Or set in Claude Code config: ```json { "mcpServers": { "gcp": { "command": "python", "args": ["-m", "gcp_mcp.cli", "--local", "--debug"], "env": { "LOG_LEVEL": "DEBUG" } } } } ``` ### Test Server Manually You can test the server works before integrating with Claude Code: ```bash # Run server and check it starts without errors python -m gcp_mcp.cli --local --debug # Should see output like: # 🐛 Debug mode enabled # 🎯 Using GCP project: your-project-id # ⚙️ Using config file: config.local.json # 🔑 Using credentials: ./gcp-mcp-credentials.json # 🚀 Starting GCP MCP Server... # 💡 Use Ctrl+C to stop the server ``` ## 📚 Next Steps Once you have the basic setup working: 1. **Explore Tools**: Try different query types to understand what each tool does 2. **Customize Configuration**: Modify `config.json` for your specific needs 3. **Add More Projects**: Configure multi-project access for enterprise features 4. **Set Up Monitoring**: Enable caching and rate limiting for production use ## 🆘 Getting Help If you run into issues: 1. Check the [troubleshooting section](#troubleshooting) above 2. Enable debug logging to see detailed error messages 3. Verify your GCP setup and permissions 4. Open an issue on GitHub with: - Your configuration (remove sensitive data) - Error logs - Steps to reproduce ## 🎯 Example Use Cases Here are some practical examples of what you can do once it's set up: ### DevOps/SRE Tasks - "Check if there are any critical errors in production right now" - "Analyze the root cause of the outage that happened 2 hours ago" - "Show me which services have the highest error rates today" ### Security Monitoring - "Look for any suspicious authentication attempts in the last 24 hours" - "Check for any privilege escalation events" - "Analyze security logs for compliance audit" ### Performance Optimization - "Find the slowest API endpoints from the last week" - "Identify which microservices are using the most resources" - "Analyze database query performance issues" ### Incident Response - "Show me all errors related to the payment service from 3pm to 4pm today" - "Trace the user request ID abc123 across all services" - "Find all related errors around the time user reported the issue"