README.md•8 kB
# 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](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http).
## Installation
```bash
# 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):
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
```
2. **Environment Variables**:
```bash
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)
```bash
# Start with stdio transport
pnpm start
# Or explicitly specify stdio
MCP_TRANSPORT=stdio pnpm start
```
### Using HTTP Transport
```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
# 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**:
```bash
gcloud auth application-default login
```
2. **Verify service account permissions**:
- Logging Viewer
- Spanner Database User
- Monitoring Viewer
- Cloud Trace User
3. **Test authentication**:
```bash
DEBUG=true pnpm start
```
### HTTP Transport Issues
1. **Port conflicts**: If port 3000 is in use, specify a different port:
```bash
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**:
```bash
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.