MCP Logging NL Query Server

This project provides a Model Context Protocol (MCP) server that allows developers and AI Agents to query Google Cloud Logging using natural language. The server uses Vertex AI Gemini 2.5 to translate natural language queries into Google Cloud Logging Query Language (LQL), then queries Cloud Logging and returns the results.

Features

• Natural language to LQL translation using Vertex AI Gemini 2.5
• Flexible log querying: filter on monitored resource, log name, severity, time, and more
• REST API for easy integration
• Ready for deployment on Google Cloud Run or GKE

API Usage

Endpoints

1. Natural Language Query

POST /logs/nl_query

Request:

{
  "query": "Show me all error logs from yesterday for my Cloud Run service 'my-service'",
  "max_results": 20
}

Response:

{
  "lql": "resource.type = \"cloud_run_revision\" AND resource.labels.service_name = \"my-service\" AND severity = ERROR AND timestamp >= \"2025-04-17T00:00:00Z\" AND timestamp < \"2025-04-18T00:00:00Z\"",
  "entries": [ ... log entries ... ]
}

2. LQL Filter Query

POST /logs/query

Request:

{
  "filter": "resource.type=\"cloud_run_revision\" AND severity=ERROR",
  "max_results": 20
}

Response:

{
  "lql": "resource.type=\"cloud_run_revision\" AND severity=ERROR",
  "entries": [ ... log entries ... ]
}

OpenAPI & Tooling

• OpenAPI/Swagger docs available at /docs and /openapi.json when running.
• Both endpoints are also discoverable as MCP tools for agent frameworks (Smithery, Claude Desktop, etc).

Example curl commands

curl -X POST $MCP_BASE_URL/logs/nl_query -H 'Content-Type: application/json' -d '{"query": "Show error logs for my Cloud Run service", "max_results": 2}'

curl -X POST $MCP_BASE_URL/logs/query -H 'Content-Type: application/json' -d '{"filter": "resource.type=\"cloud_run_revision\" AND severity=ERROR", "max_results": 2}'

Tests

• Example test script: test_main.py (see repo)

.gitignore

• Standard Python ignores included (see repo)

Deployment

Running on Google Cloud Run

You can deploy this server to Google Cloud Run for a fully managed, scalable solution.

Steps:

1. Build the Docker image:

   gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/mcp-logging-server
   

2. Deploy to Cloud Run:

   gcloud run deploy mcp-logging-server \
     --image gcr.io/YOUR_PROJECT_ID/mcp-logging-server \
     --platform managed \
     --region YOUR_REGION \
     --allow-unauthenticated \
     --port 8080
   

   Replace YOUR_PROJECT_ID and YOUR_REGION with your actual GCP project ID and region (e.g., us-central1).

3. Set Environment Variables:

   • In the Cloud Run deployment UI or with the --set-env-vars flag, provide:
     • VERTEX_PROJECT=your-gcp-project-id
     • VERTEX_LOCATION=us-central1 (or your region)
   • Credentials:
     • Prefer using the Cloud Run service account with the right IAM roles (Logging Viewer, Vertex AI User).
     • You usually do NOT need to set GOOGLE_APPLICATION_CREDENTIALS on Cloud Run unless using a non-default service account key.

4. IAM Permissions:

   • Ensure the Cloud Run service account has:
     • roles/logging.viewer
     • roles/aiplatform.user

5. Accessing the Service:

   • After deployment, Cloud Run will provide a service URL (e.g., https://mcp-logging-server-xxxxxx.a.run.app).
   • Use this as your $MCP_BASE_URL in API requests.

Google Cloud Authentication Setup

This project requires Google Cloud Application Default Credentials (ADC) to access Logging and Vertex AI APIs.

Steps to Set Up Credentials:

1. Create a Service Account:
   • Go to the Google Cloud Console → IAM & Admin → Service Accounts.
   • Select your project.
   • Create or select a service account with permissions: Logging Viewer and Vertex AI User.
2. Create and Download a Key:
   • In the Service Account, click "Manage keys" → "Add key" → "Create new key" (choose JSON).
   • Download the JSON key file to your computer.
3. Set the Environment Variable:
   • In your terminal, set the environment variable to the path of your downloaded key:

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

   • Replace /path/to/your/service-account-key.json with the actual path.
4. (Optional) Set Project and Location:
   • You may also need:

     export VERTEX_PROJECT=your-gcp-project-id
     export VERTEX_LOCATION=us-central1
     

5. Verify Authentication:
   • Run a simple gcloud or Python client call to ensure authentication is working.
   • If you see DefaultCredentialsError, check your environment variable and file path.

Prerequisites

• Python 3.9+
• Google Cloud project with Logging and Vertex AI APIs enabled
• Service account with permissions for Logging Viewer and Vertex AI User
• Set environment variables:
  • VERTEX_PROJECT: Your GCP project ID
  • VERTEX_LOCATION: Vertex AI region (default: us-central1)
  • GOOGLE_APPLICATION_CREDENTIALS: Path to your service account JSON key file

Local Development

pip install -r requirements.txt
export VERTEX_PROJECT=your-project-id
export VERTEX_LOCATION=us-central1
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
python main.py

Deploy to Cloud Run

gcloud builds submit --tag gcr.io/$VERTEX_PROJECT/mcp-logging-server
 gcloud run deploy mcp-logging-server \
    --image gcr.io/$VERTEX_PROJECT/mcp-logging-server \
    --platform managed \
    --region $VERTEX_LOCATION \
    --allow-unauthenticated

Example Natural Language Queries

• Show all logs from Kubernetes clusters
• Show error logs from Compute Engine and AWS EC2 instances
• Find Admin Activity audit logs for project my-project
• Find logs containing the word unicorn
• Find logs with both unicorn and phoenix
• Find logs where textPayload contains both unicorn and phoenix
• Find logs where textPayload contains the phrase 'unicorn phoenix'
• Show logs from yesterday for Cloud Run service 'my-service'
• Show logs from the last 30 minutes
• Show logs for logName containing request_log in GKE
• Show logs where pod_name matches foo or bar using regex
• Show logs for Compute Engine where severity is WARNING or higher
• Show logs for Cloud SQL instances in us-central1
• Show logs for Pub/Sub topics containing 'payments'
• Show logs for log entries between two timestamps
• Show logs where jsonPayload.message matches regex 'foo.*bar'
• Show logs where labels.env is not prod

For more LQL examples, see the official documentation.

License

Apache 2.0