tareqmamari/cloud-logs-mcp

IBM Cloud Logs MCP Server

Model Context Protocol (MCP) server for IBM Cloud Logs, enabling AI assistants to interact with IBM Cloud Logs instances.

Overview

This MCP server provides comprehensive access to IBM Cloud Logs through 88 tools covering queries, alerts, dashboards, policies, webhooks, streams, and more.

Key Features:

• Complete IBM Cloud Logs API coverage (88 tools)
• IBM Cloud IAM authentication with automatic token refresh
• Retry logic with exponential backoff
• Configurable rate limiting
• Health checks and metrics tracking
• Structured logging

Quick Start

Installation

Option 1: Homebrew (Recommended)

brew tap tareqmamari/tap
brew install logs-mcp-server
logs-mcp-server --version

Option 2: Build from Source

git clone https://github.com/tareqmamari/logs-mcp-server.git
cd logs-mcp-server
make deps && make build

Configuration

Prerequisites

1. Get IBM Cloud credentials:
   • API Key: https://cloud.ibm.com/iam/apikeys
   • Service URL: https://[instance-id].api.[region].logs.cloud.ibm.com
   • Region: us-south, eu-de, au-syd, etc.

For Claude Desktop

Configuration file: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ibm-cloud-logs": {
      "command": "logs-mcp-server",
      "env": {
        "LOGS_SERVICE_URL": "https://[your-instance-id].api.[region].logs.cloud.ibm.com",
        "LOGS_API_KEY": "your-ibm-cloud-api-key"
      }
    }
  }
}

After setup: Restart Claude Desktop and ask "List my IBM Cloud Logs alerts"

For Microsoft 365 Copilot

Prerequisites:

• Microsoft 365 Copilot subscription (Enterprise or Business)
• Windows 11 or Windows 10 with Microsoft 365 apps
• Admin access to configure organization settings (for enterprise deployment)

Configuration Options:

Option 1: Personal Setup (Environment Variables)

# PowerShell (Windows)
$env:LOGS_SERVICE_URL = "https://[your-instance-id].api.[region].logs.cloud.ibm.com"
$env:LOGS_API_KEY = "your-ibm-cloud-api-key"

# Run the server
logs-mcp-server

Option 2: Enterprise Deployment (Microsoft 365 Admin Center)

For organization-wide deployment, configure through Microsoft 365 Admin Center:

1. Navigate to Settings > Integrated apps > Copilot extensions
2. Add custom MCP server with the following configuration:
   • Name: IBM Cloud Logs
   • Command: logs-mcp-server
   • Environment Variables:
     • LOGS_SERVICE_URL: Your IBM Cloud Logs endpoint
     • LOGS_API_KEY: Service ID API key (recommended for enterprise)

After setup:

• In Microsoft 365 Copilot, ask "Query my IBM Cloud Logs for errors"
• In Microsoft Teams, use "@Copilot list my dashboards in IBM Cloud Logs"
• In Outlook, ask "Show me alerts from IBM Cloud Logs"

Note: Microsoft 365 Copilot MCP support is currently in preview. Configuration steps may vary by tenant settings. See for alternative setup methods.

For Other MCP Clients

See for setup instructions for Cline, programmatic usage, and other MCP-compatible clients.

API Reference

Tools

88 tools organized by functionality:

Query Operations (5 tools)

• query_logs, submit_background_query, get_background_query_status, get_background_query_data, cancel_background_query

Log Ingestion (1 tool)

• ingest_logs

Alert Management (11 tools)

• list_alerts, get_alert, create_alert, update_alert, delete_alert
• list_alert_definitions, get_alert_definition, create_alert_definition, update_alert_definition, delete_alert_definition
• suggest_alert - SRE-grade alert recommendations (see Alert Intelligence below)

Dashboard Management (14 tools)

• list_dashboards, get_dashboard, create_dashboard, update_dashboard, delete_dashboard
• list_dashboard_folders, get_dashboard_folder, create_dashboard_folder, update_dashboard_folder, delete_dashboard_folder
• move_dashboard_to_folder, pin_dashboard, unpin_dashboard, set_default_dashboard

Policies (5 tools)

• list_policies, get_policy, create_policy, update_policy, delete_policy

Webhooks (5 tools)

• list_outgoing_webhooks, get_outgoing_webhook, create_outgoing_webhook, update_outgoing_webhook, delete_outgoing_webhook

Events to Metrics - E2M (5 tools)

• list_e2m, get_e2m, create_e2m, replace_e2m, delete_e2m

Rule Groups (5 tools)

• list_rule_groups, get_rule_group, create_rule_group, update_rule_group, delete_rule_group

Data Access Rules (5 tools)

• list_data_access_rules, get_data_access_rule, create_data_access_rule, update_data_access_rule, delete_data_access_rule

Enrichments (5 tools)

• list_enrichments, get_enrichment, create_enrichment, update_enrichment, delete_enrichment

Streams (5 tools)

• list_streams, get_stream, create_stream, update_stream, delete_stream

Views (5 tools)

• list_views, get_view, create_view, replace_view, delete_view

Resources

Prompts

Alert Intelligence

The suggest_alert tool provides SRE-grade alert recommendations based on industry best practices from Google SRE, the RED/USE methodologies, and academic research on alerting.

Why Use suggest_alert?

Quick Start

"Suggest an alert for high error rate on my API service with 99.9% SLO"
"What alerts should I create for my Kafka cluster?"
"Help me set up monitoring for my PostgreSQL database"

Key Parameters

Supported Service Types

RED Method (Rate, Errors, Duration) for services:

• web_service, api_gateway, worker, microservice, serverless

USE Method (Utilization, Saturation, Errors) for resources:

• database, cache, message_queue, kubernetes, storage

Example Output

{
  "suggestions": [{
    "name": "API Error Rate - Fast Burn (Page)",
    "severity": "P1",
    "methodology": "RED",
    "burn_rate_condition": {
      "slo_target": 0.999,
      "burn_rate": 14.4,
      "window_duration": "1h",
      "consumption_percent": 2.0
    },
    "suggested_actions": [
      "1. Check error logs for patterns",
      "2. Review recent deployments",
      "3. Verify dependent service health"
    ],
    "runbook_url": "/runbooks/web_service/error-rate"
  }]
}

References

The alerting engine implements recommendations from:

• Google SRE Handbook - Alerting
• "My Philosophy on Alerting" by Rob Ewaschuk
• SRE Workbook - Alerting on SLOs

Usage Examples

"Search logs for errors in the last hour"
"Create an alert when error rate exceeds 100 per minute"
"Suggest alerts for my web service with 99.9% SLO"
"What monitoring should I set up for my Redis cache?"
"List all my dashboards"
"Ingest a test log message for my-app"
"Show me all retention policies"

Configuration

Environment Variables

Required

Plus one of the following:

• LOGS_SERVICE_URL - Full service endpoint URL (region and instance ID are auto-extracted), OR
• LOGS_REGION + LOGS_INSTANCE_ID - Region and instance ID (service URL is constructed)

Optional

Multiple Instances

Configure multiple IBM Cloud Logs instances:

{
  "mcpServers": {
    "logs-production": {
      "command": "logs-mcp-server",
      "env": {
        "LOGS_SERVICE_URL": "https://prod-id.api.us-south.logs.cloud.ibm.com",
        "LOGS_API_KEY": "prod-api-key",
        "LOGS_REGION": "us-south",
        "LOGS_INSTANCE_NAME": "Production US"
      }
    },
    "logs-staging": {
      "command": "logs-mcp-server",
      "env": {
        "LOGS_SERVICE_URL": "https://stage-id.api.us-south.logs.cloud.ibm.com",
        "LOGS_API_KEY": "staging-api-key",
        "LOGS_REGION": "us-south",
        "LOGS_INSTANCE_NAME": "Staging US"
      }
    }
  }
}

Security

Best Practices:

• Use environment variables for API keys (never hardcode)
• Use service IDs instead of personal API keys for production
• Enable TLS verification (LOGS_TLS_VERIFY=true)
• Rotate API keys regularly (recommended: 90 days)
• Apply principle of least privilege (Viewer/Operator roles)

See for comprehensive security guidance.

Development

Prerequisites

• Go 1.23.2+
• Make

Building

make deps      # Download dependencies
make build     # Build binary
make test      # Run tests
make lint      # Run linters

Project Structure

├── main.go                    # Entry point
├── internal/
│   ├── auth/                  # IBM Cloud IAM authentication
│   ├── client/                # HTTP client with retry/rate limiting
│   ├── config/                # Configuration management
│   ├── tools/                 # MCP tool implementations (70+ tools)
│   ├── server/                # MCP server
│   ├── health/                # Health checks
│   └── metrics/               # Metrics tracking
├── Makefile                   # Build automation
└── .goreleaser.yaml           # Release configuration

See for detailed development guide including:

• Setting up other MCP clients (GitHub Copilot, Cline, etc.)
• Updating API definitions
• Adding new tools
• Testing strategies
• Release process

Troubleshooting

Debug mode:

{
  "env": {
    "LOG_LEVEL": "debug",
    "LOG_FORMAT": "console"
  }
}

Support

• Issues: GitHub Issues
• IBM Cloud Logs Docs: https://cloud.ibm.com/docs/cloud-logs
• IBM Cloud Logs API: https://cloud.ibm.com/apidocs/logs-service-api

License

Copyright (c) 2025. All rights reserved.