☁️

Cloud Logs MCP

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

0 installs

1 stars

2 forks

Trust: 59 — Fair

Cloud

Installation

npx cloud-logs-mcp

Ask AI about Cloud Logs MCP

I know everything about Cloud Logs MCP. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

IBM Cloud Logs MCP Server

Model Context Protocol (MCP) server for IBM Cloud Logs, enabling AI assistants to interact with IBM Cloud Logs instances. Includes 8 portable Agent Skills for use with Claude Code, Cursor, Gemini CLI, GitHub Copilot, and 30+ other agents.

Overview

This project provides two complementary ways to work with IBM Cloud Logs through AI agents:

	MCP Server	Agent Skills
What	Running Go server with 88 tools via JSON-RPC	8 portable instruction bundles (markdown + JSON)
When	Real-time log queries, CRUD operations, live monitoring	Query writing, architecture guidance, offline reference
Requires	Binary + API key + network	Nothing — loaded on-demand by your agent
Works with	Claude Desktop, any MCP client	Claude Code, Cursor, Gemini CLI, GitHub Copilot, 30+ agents

Key Features:

Complete IBM Cloud Logs API coverage (88 tools)
8 embedded Agent Skills following the agentskills.io open standard
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

Agent Skills are automatically installed to ~/.agents/skills/ after Homebrew install.

Option 2: Build from Source

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

Configuration

Prerequisites

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:

Navigate to Settings > Integrated apps > Copilot extensions
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 CONTRIBUTING.md for alternative setup methods.

For Other MCP Clients

See CONTRIBUTING.md 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

Resource URI	Description
`config://current`	Server configuration
`metrics://server`	Server metrics
`health://status`	Health check status

Prompts

Prompt	Description
`investigate_errors`	Guide for investigating error spikes
`setup_monitoring`	Setup monitoring for a service
`test_log_ingestion`	Test log ingestion workflow
`create_dashboard_workflow`	Dashboard creation wizard
`compare_environments`	Compare different environments
`debugging_workflow`	Systematic debugging approach
`optimize_retention`	Optimize log retention costs

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`?

Problem	How `suggest_alert` Helps
Alert fatigue	Uses burn rate alerting to reduce noise by 90%+
False positives	Multi-window validation prevents flapping alerts
Static thresholds	Suggests dynamic baselines for seasonal metrics
Missing context	Auto-generates runbook templates and actions
Wrong methodology	Auto-selects RED (services) vs USE (resources)

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

Parameter	Description	Example
`service_type`	Component type (auto-detected if not provided)	`web_service`, `database`, `message_queue`
`slo_target`	SLO target (enables burn rate alerting)	`0.999` (99.9%)
`is_user_facing`	Affects severity classification	`true` → P1 eligible
`use_case`	Natural language description	`"high latency on checkout"`

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

Agent Skills

The binary embeds 8 Agent Skills following the agentskills.io open standard. Skills are portable instruction bundles that work across 30+ AI agents — no runtime, authentication, or network required.

Available Skills

Skill	Description
`ibm-cloud-logs-query`	DataPrime and Lucene query writing, validation, and auto-correction
`ibm-cloud-logs-alerting`	SRE-grade alerting with RED/USE methodologies and burn rate math
`ibm-cloud-logs-incident-investigation`	Systematic incident investigation with heuristic pattern matching
`ibm-cloud-logs-dashboards`	Dashboard design with DataPrime-powered widgets
`ibm-cloud-logs-cost-optimization`	TCO policies, data tier selection, and Events-to-Metrics
`ibm-cloud-logs-ingestion`	Log ingestion, parsing rules, and enrichments
`ibm-cloud-logs-access-control`	Data access rules, audit logging, and compliance patterns
`ibm-cloud-logs-api-reference`	Full API reference for all 88 tool endpoints

Installing Skills

Skills are embedded in the binary. Use the skills subcommand to manage them.

# Install to ~/.agents/skills/ (user-level, available to all projects)
logs-mcp-server skills install

# Install to ./.agents/skills/ (project-level, current project only)
logs-mcp-server skills install --project

# List all available skills
logs-mcp-server skills list

# Remove installed skills
logs-mcp-server skills remove

If you installed via Homebrew, skills are automatically installed to ~/.agents/skills/ on first install.

How Skills Work

Skills use a progressive disclosure model to minimize context window usage:

Catalog (~200 tokens) — your agent sees skill names and descriptions
SKILL.md (~300 lines) — loaded on-demand when a skill activates
References — detailed docs loaded only when deeper information is needed

This means skills consume ~2K tokens on-demand compared to the MCP server's ~25K fixed overhead per conversation. See BENCHMARK.md for a detailed comparison.

Compatible Agents

Skills work with any agent that can read markdown files from ~/.agents/skills/ or ./.agents/skills/:

Claude Code — auto-discovers skills from ~/.agents/skills/
Cursor — reads project-level .agents/skills/
Gemini CLI — reads ~/.agents/skills/
GitHub Copilot — reads project-level skills
Bob, Windsurf, Cline, Aider — and 20+ more via the agentskills.io standard

When to Use Skills vs MCP

Scenario	Use
Query real-time logs	MCP
Write a DataPrime query (no execution)	Skills
Create or manage alerts	MCP
Design an alerting strategy	Skills
Debug a live production incident	MCP
Learn investigation methodology	Skills
Set up dashboards	MCP
Plan dashboard layout and queries	Skills
Offline query/config guidance (no execution)	Skills
Any CRUD operation on IBM Cloud Logs	MCP

For maximum effectiveness, use both together — skills provide the domain knowledge, MCP executes the actions.

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

Variable	Description
`LOGS_API_KEY`	IBM Cloud API key

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

Variable	Default	Description
`LOGS_TIMEOUT`	`30s`	HTTP request timeout
`LOGS_MAX_RETRIES`	`3`	Maximum retry attempts
`LOGS_RATE_LIMIT`	`100`	Requests per second
`LOG_LEVEL`	`info`	Log level (debug/info/warn/error)
`LOG_FORMAT`	`json`	Log format (json/console)

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

MCP Server 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)
Use data access rules to restrict log visibility by team or role
Enable audit logging (LOG_LEVEL=debug) for compliance tracking

Agent Skills Security:

Skills contain no credentials, tokens, or connection strings
Embedded in the binary via go:embed — immutable after build
Zero network attack surface — no API calls, no data access
The ibm-cloud-logs-access-control skill includes security query templates (auth failures, privilege escalation, sensitive data access) and compliance patterns (GDPR, SOC 2, multi-tenant isolation)

See BENCHMARK.md for a detailed MCP vs Skills security comparison.

See SECURITY.md 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 with skills subcommand
├── embed_skills.go            # Embeds .agents/skills/ into binary
├── .agents/skills/            # 8 Agent Skills (agentskills.io format)
│   ├── ibm-cloud-logs-query/         # DataPrime query writing & validation
│   ├── ibm-cloud-logs-alerting/      # SRE-grade alerting with burn rate math
│   ├── ibm-cloud-logs-incident-investigation/
│   ├── ibm-cloud-logs-dashboards/
│   ├── ibm-cloud-logs-cost-optimization/
│   ├── ibm-cloud-logs-ingestion/
│   ├── ibm-cloud-logs-access-control/
│   └── ibm-cloud-logs-api-reference/
├── internal/
│   ├── auth/                  # IBM Cloud IAM authentication
│   ├── client/                # HTTP client with retry/rate limiting
│   ├── config/                # Configuration management
│   ├── tools/                 # MCP tool implementations (88 tools)
│   ├── skills/                # Skill installer
│   ├── server/                # MCP server
│   ├── health/                # Health checks
│   └── metrics/               # Metrics tracking
├── Makefile                   # Build automation
└── .goreleaser.yaml           # Release configuration

See CONTRIBUTING.md 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

Issue	Solution
Tools not showing	Use absolute binary path, restart MCP client completely
`401 Unauthorized`	Check API key validity and IAM permissions
`429 Too Many Requests`	Reduce `LOGS_RATE_LIMIT` or request quota increase
Connection timeout	Increase `LOGS_TIMEOUT` or check network

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

Cloud Logs MCP

Installation

Reviews

Documentation

IBM Cloud Logs MCP Server

Overview

Quick Start

Installation

Configuration

Prerequisites

For Claude Desktop

For Microsoft 365 Copilot

For Other MCP Clients

API Reference

Tools

Query Operations (5 tools)

Log Ingestion (1 tool)

Alert Management (11 tools)

Dashboard Management (14 tools)

Policies (5 tools)

Webhooks (5 tools)

Events to Metrics - E2M (5 tools)

Rule Groups (5 tools)

Data Access Rules (5 tools)

Enrichments (5 tools)

Streams (5 tools)

Views (5 tools)

Resources

Prompts

Alert Intelligence

Why Use suggest_alert?

Quick Start

Key Parameters

Supported Service Types

Example Output

References

Agent Skills

Available Skills

Installing Skills

How Skills Work

Compatible Agents

When to Use Skills vs MCP

Usage Examples

Configuration

Environment Variables

Required

Optional

Multiple Instances

Security

Development

Prerequisites

Building

Project Structure

Troubleshooting

Support

License

Why Use `suggest_alert`?