gcp-telemetry-mcp

kitagry/gcp-telemetry-mcp

3.4

If you are the rightful owner of gcp-telemetry-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for Google Cloud Platform telemetry services, providing seamless integration with GCP observability tools.

GCP Telemetry MCP Server

A Model Context Protocol (MCP) server for Google Cloud Platform telemetry services, providing seamless integration with GCP observability tools.

Features

Cloud Logging

  • āœ… Write log entries with structured data
  • āœ… Support for multiple severity levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • āœ… Custom labels and structured payloads
  • āœ… List log entries with filtering and pagination

Cloud Monitoring

  • āœ… Create custom metric descriptors
  • āœ… Write time series data points
  • āœ… Query time series data with advanced filtering
  • āœ… Support for all metric kinds (GAUGE, DELTA, CUMULATIVE)
  • āœ… Support for all value types (BOOL, INT64, DOUBLE, STRING, DISTRIBUTION)
  • āœ… Advanced aggregation options (alignment periods, reducers)
  • āœ… Delete custom metric descriptors
  • āœ… List available metric descriptors
  • āœ… Discover available Google Cloud service metrics

Cloud Trace

  • āœ… List traces with advanced filtering and pagination
  • āœ… Get specific traces by trace ID
  • āœ… Update/patch trace spans with new data
  • āœ… Support for distributed trace analysis

Cloud Profiler

  • āœ… Create new profiling sessions for applications
  • āœ… Create offline profiles with existing profiling data
  • āœ… Update profile metadata and data
  • āœ… List profiles with pagination
  • āœ… Support for multiple profile types (CPU, HEAP, THREADS, CONTENTION, WALL)

Prerequisites

  • Go 1.24.2 or later
  • Google Cloud Project with appropriate APIs enabled
  • Authentication credentials configured (see Authentication)

Installation

From Source

git clone https://github.com/kitagry/gcp-telemetry-mcp.git
cd gcp-telemetry-mcp
go build -o gcp-telemetry-mcp

Authentication

This server uses Google Cloud authentication. Configure one of the following:

  1. Service Account Key File:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

  2. Application Default Credentials (if running on GCP):

    gcloud auth application-default login

  3. Workload Identity (for GKE/Cloud Run deployments)

Configuration

Set the required environment variable:

export GOOGLE_CLOUD_PROJECT="your-project-id"

Usage

Running the Server

./gcp-telemetry-mcp

Or with Go:

go run main.go

MCP Tools

The server provides the following MCP tools:

Cloud Logging Tools

write_log_entry

Write a log entry to Cloud Logging.

Parameters:

  • log_name (string, required): Name of the log to write to
  • severity (string, required): Log severity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • message (string, required): Log message
  • labels (object, optional): Key-value pairs for log labels
  • payload (object, optional): Structured data payload

Example:

{
  "log_name": "my-application-log",
  "severity": "INFO",
  "message": "User login successful",
  "labels": {
    "user_id": "12345",
    "environment": "production"
  },
  "payload": {
    "event": "user_login",
    "timestamp": "2024-01-01T12:00:00Z",
    "ip_address": "192.168.1.1"
  }
}
list_log_entries

List log entries from Cloud Logging.

Parameters:

  • filter (string, optional): Cloud Logging filter expression
  • limit (number, optional): Maximum number of entries to return (default: 50)

Example:

{
  "filter": "severity>=ERROR",
  "limit": 100
}

Cloud Monitoring Tools

create_metric_descriptor

Create a custom metric descriptor in Cloud Monitoring.

Parameters:

  • type (string, required): Metric type (e.g., 'custom.googleapis.com/my_metric')
  • metric_kind (string, required): Metric kind (GAUGE, DELTA, or CUMULATIVE)
  • value_type (string, required): Value type (BOOL, INT64, DOUBLE, STRING, or DISTRIBUTION)
  • description (string, required): Description of the metric
  • display_name (string, optional): Display name for the metric

Example:

{
  "type": "custom.googleapis.com/app/response_time",
  "metric_kind": "GAUGE",
  "value_type": "DOUBLE",
  "description": "Application response time in seconds",
  "display_name": "App Response Time"
}
write_time_series

Write time series data to Cloud Monitoring.

Parameters:

  • metric_type (string, required): Metric type to write data for
  • resource_type (string, required): Resource type (e.g., 'global', 'gce_instance')
  • value (number, required): Metric value to write
  • metric_labels (object, optional): Optional metric labels
  • timestamp (string, optional): Timestamp for the data point (ISO 8601 format, defaults to now)

Example:

{
  "metric_type": "custom.googleapis.com/app/response_time",
  "resource_type": "global",
  "value": 0.125,
  "metric_labels": {
    "service": "api",
    "version": "v1.2.0"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
list_time_series

List time series data from Cloud Monitoring.

Parameters:

  • filter (string, required): Monitoring filter expression
  • start_time (string, required): Start time for the query (ISO 8601 format)
  • end_time (string, required): End time for the query (ISO 8601 format)
  • aggregation (object, optional): Aggregation configuration

Example:

{
  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/usage\"",
  "start_time": "2024-01-01T10:00:00Z",
  "end_time": "2024-01-01T12:00:00Z",
  "aggregation": {
    "alignment_period": "60s",
    "per_series_aligner": "ALIGN_MEAN",
    "cross_series_reducer": "REDUCE_MEAN",
    "group_by_fields": ["resource.zone"]
  }
}
list_metric_descriptors

List metric descriptors from Cloud Monitoring.

Parameters:

  • filter (string, optional): Filter expression for metric descriptors

Example:

{
  "filter": "metric.type=starts_with(\"custom.googleapis.com/\")"
}
delete_metric_descriptor

Delete a custom metric descriptor from Cloud Monitoring.

Parameters:

  • metric_type (string, required): Metric type to delete

Example:

{
  "metric_type": "custom.googleapis.com/my_old_metric"
}
list_available_metrics

List available metrics in Cloud Monitoring including Google Cloud service metrics.

Parameters:

  • filter (string, optional): Filter expression for metrics (e.g., 'metric.type=starts_with("compute.googleapis.com/")')
  • page_size (number, optional): Maximum number of metrics to return (default: 100)
  • page_token (string, optional): Page token for pagination

Example:

{
  "filter": "metric.type=starts_with(\"compute.googleapis.com/\")",
  "page_size": 50
}

Cloud Trace Tools

list_traces

List traces from Cloud Trace.

Parameters:

  • start_time (string, required): Start time for the query (ISO 8601 format)
  • end_time (string, required): End time for the query (ISO 8601 format)
  • filter (string, optional): Filter expression (e.g., 'span_name_prefix:"api"')
  • order_by (string, optional): Order by field (e.g., 'start_time desc')
  • page_size (number, optional): Maximum number of traces to return (default: 100)
  • page_token (string, optional): Page token for pagination

Example:

{
  "start_time": "2024-01-01T10:00:00Z",
  "end_time": "2024-01-01T12:00:00Z",
  "filter": "span_name_prefix:\"api\"",
  "order_by": "start_time desc",
  "page_size": 50
}
get_trace

Get a specific trace from Cloud Trace.

Parameters:

  • trace_id (string, required): Trace ID to retrieve

Example:

{
  "trace_id": "1234567890abcdef1234567890abcdef"
}
patch_traces

Update trace spans in Cloud Trace.

Parameters:

  • trace_id (string, required): Trace ID to update
  • spans (array, required): Array of span objects to update or create

Example:

{
  "trace_id": "1234567890abcdef1234567890abcdef",
  "spans": [
    {
      "span_id": "span123",
      "name": "updated-operation",
      "start_time": "2024-01-01T12:00:00Z",
      "end_time": "2024-01-01T12:00:05Z",
      "parent_id": "parent123",
      "kind": "RPC_CLIENT",
      "labels": {
        "service": "api",
        "version": "v2.0"
      }
    }
  ]
}

Cloud Profiler Tools

create_profile

Create a new profile in Cloud Profiler.

Parameters:

  • target (string, required): Target deployment name
  • profile_type (string, required): Profile type (CPU, HEAP, THREADS, CONTENTION, or WALL)
  • duration (string, optional): Profile duration (e.g., '60s', '5m', defaults to '60s')
  • labels (object, optional): Optional labels for the profile

Example:

{
  "target": "my-app-v1",
  "profile_type": "CPU",
  "duration": "60s",
  "labels": {
    "service": "web-server",
    "version": "v1.2.0"
  }
}
create_offline_profile

Create an offline profile in Cloud Profiler with existing profiling data.

Parameters:

  • target (string, required): Target deployment name
  • profile_type (string, required): Profile type (CPU, HEAP, THREADS, CONTENTION, or WALL)
  • profile_data (string, required): Base64-encoded profile data
  • duration (string, optional): Profile duration (e.g., '60s', '5m')
  • labels (object, optional): Optional labels for the profile

Example:

{
  "target": "my-app-v1",
  "profile_type": "HEAP",
  "profile_data": "base64encodedprofiledata==",
  "duration": "30s",
  "labels": {
    "service": "api-server",
    "environment": "production"
  }
}
update_profile

Update a profile in Cloud Profiler.

Parameters:

  • profile_name (string, required): Profile name to update
  • profile_data (string, optional): Updated base64-encoded profile data
  • labels (object, optional): Updated labels for the profile
  • update_mask (string, optional): Fields to update (e.g., 'labels,profile_bytes')

Example:

{
  "profile_name": "projects/my-project/profiles/12345",
  "profile_data": "newbase64encodeddata==",
  "labels": {
    "service": "updated-service",
    "version": "v1.3.0"
  },
  "update_mask": "labels,profile_bytes"
}
list_profiles

List profiles from Cloud Profiler.

Parameters:

  • page_size (number, optional): Maximum number of profiles to return (default: 100)
  • page_token (string, optional): Page token for pagination

Example:

{
  "page_size": 50,
  "page_token": "next_page_token_here"
}

Development

Running Tests

go test ./...

Project Structure

.
ā”œā”€ā”€ main.go              # MCP server implementation and tool handlers
ā”œā”€ā”€ logging/
ā”‚   ā”œā”€ā”€ client.go        # Cloud Logging client implementation
ā”‚   ā””ā”€ā”€ client_test.go   # Tests for logging client
ā”œā”€ā”€ monitoring/
ā”‚   ā”œā”€ā”€ client.go        # Cloud Monitoring client implementation
ā”‚   ā””ā”€ā”€ client_test.go   # Tests for monitoring client
ā”œā”€ā”€ trace/
ā”‚   ā”œā”€ā”€ client.go        # Cloud Trace client implementation
ā”‚   ā””ā”€ā”€ client_test.go   # Tests for trace client
ā”œā”€ā”€ profiler/
ā”‚   ā”œā”€ā”€ client.go        # Cloud Profiler client implementation
ā”‚   ā””ā”€ā”€ client_test.go   # Tests for profiler client
ā”œā”€ā”€ go.mod               # Go module definition
ā”œā”€ā”€ go.sum               # Go dependency checksums
ā””ā”€ā”€ README.md           # This file

Error Handling

The server provides detailed error messages for common issues:

  • Missing GOOGLE_CLOUD_PROJECT environment variable
  • Authentication failures
  • Invalid parameters for logging and monitoring operations
  • Cloud Logging API errors
  • Cloud Monitoring API errors
  • Time series data validation errors
  • Metric descriptor creation/deletion failures
  • Cloud Trace API errors
  • Trace retrieval and span update failures
  • Cloud Profiler API errors
  • Profile creation and update failures

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

License

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

Support

For issues and questions:

  • Create an issue in the GitHub repository
  • Check Google Cloud Logging documentation for logging-specific questions
  • Check Google Cloud Monitoring documentation for monitoring-specific questions
  • Check Google Cloud Trace documentation for trace-specific questions
  • Check Google Cloud Profiler documentation for profiler-specific questions