mcp-oci-metrics-server by adibirzu - MCP Server

Enhanced OCI Metrics MCP Server

A Model Context Protocol (MCP) server that provides Oracle Cloud Infrastructure (OCI) monitoring metrics access for Large Language Models with Grafana collection model architecture. This enhanced server enables LLMs to query, analyze, and visualize OCI metrics through multi-tenancy support, advanced MQL queries, and template variables.

🆕 Enhanced Features (v2.0)

🏢 Multi-Tenancy Support

Query metrics across multiple OCI tenancies
Instance Principal and User Principal authentication
Automatic tenancy discovery from OCI config
Cross-tenancy metric comparison

🔍 Advanced MQL (Metric Query Language)

Enhanced OCI-compliant syntax: CpuUtilization[5m].mean(), rate(NetworksBytesIn[1m])
Fuzzy matching: CpuUtilization[1m]{resourceDisplayName =~ "prod*"}.mean()
Alarm conditions: CpuUtilization[5m].mean() > 80
Join operations: CpuUtilization[5m].mean() && MemoryUtilization[5m].mean()
Absence detection: CpuUtilization[1m].absent(5m)
Arithmetic operations: TotalRequestLatency[1m].mean() / 1000
Query validation and suggestions
Template-based queries with variable substitution
Full aggregation support: mean, sum, max, min, rate, percentile, absent, stddev

📊 Template Variables

Dynamic dashboard variables (compartment, instance, namespace, metric)
Query-based variable resolution
Variable dependency management
Auto-refresh on time range changes

🔐 Enhanced Authentication

Instance Principal (for OCI-hosted environments)
User Principal with multiple profile support
Automatic authentication context detection
Connection health monitoring

⚙️ Grafana-Style Datasource Management

Datasource configuration with validation
Export/import configuration for backup
Real-time connection testing
Multi-region support

✨ Core Features

🔍 Query OCI Metrics: Access metrics from OCI Monitoring, Stack Monitoring, DB Management, and OPS Insights
📊 LLM-Compatible Visualizations: ASCII charts and data tables that work in any LLM context
🌐 Interactive Charts: Optional Plotly.js charts for web browser environments
🔄 Instance Correlation: Correlate metrics across compute instances and services
🎯 Anomaly Detection: Prepare metrics data for anomaly detection workflows
⚡ Multiple Interfaces: Enhanced and standard MCP server implementations

🚀 Quick Start

Node.js 18.0 or higher
OCI CLI configured with proper credentials
Python 3.8+ (for FastMCP server)
Valid OCI account with monitoring permissions

1. Clone and Setup

git clone https://github.com/your-username/mcp-oci-metrics-server.git
cd mcp-oci-metrics-server
npm install

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env with your OCI details
OCI_COMPARTMENT_ID=ocid1.compartment.oc1..your-compartment-id
OCI_REGION=us-ashburn-1

3. Setup OCI CLI

# Configure OCI CLI (one-time setup)
oci setup config

# Verify configuration
oci iam compartment list

4. Build and Test

# Build TypeScript
npm run build

# Start enhanced server (default)
npm start

# Or start standard server
npm run start:standard

# Test the server
node test-server.js

5. Configure Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "oci-metrics": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-oci-metrics-server/dist/index.js"],
      "env": {
        "OCI_COMPARTMENT_ID": "your-compartment-ocid",
        "OCI_REGION": "your-region"
      }
    }
  }
}

🛠️ Available Tools

Enhanced Tools (v2.0)

1. `manage_datasource_config`

Manage OCI datasource configuration with multi-tenancy support.

Actions: list, add, remove, set_default, test, export, import

Example:

{
  "action": "list"
}

2. `query_mql`

Execute MQL (Metric Query Language) queries with enhanced OCI-compliant syntax.

Parameters:

query (required): MQL query string with full OCI syntax support
namespace (required): OCI namespace
tenancyId (optional): Tenancy to use for query
timeRange (optional): Time range override
variables (optional): Template variables

Supported MQL Features:

Time windows: 1m-60m, 1h-24h, 1d
Aggregations: mean(), max(), min(), sum(), count(), percentile(p), absent()
Operators: >, <, >=, <=, ==, !=, =~, !~, in, not in
Functions: rate(), groupBy(), grouping()
Joins: && (AND), || (OR)
Arithmetic: +, -, *, /, %

Examples:

// Basic percentile query
{
  "query": "CpuUtilization[5m].percentile(95)",
  "namespace": "oci_computeagent"
}

// Fuzzy matching with threshold
{
  "query": "CpuUtilization[5m]{resourceDisplayName =~ \"web*\"}.mean() > 80",
  "namespace": "oci_computeagent"
}

// Absence detection
{
  "query": "CpuUtilization[1m].groupBy(resourceId).absent(5m)",
  "namespace": "oci_computeagent"
}

// Join operation
{
  "query": "CpuUtilization[5m].mean() > 80 && MemoryUtilization[5m].mean() > 70",
  "namespace": "oci_computeagent"
}

3. `validate_mql`

Validate MQL query syntax and get suggestions for corrections.

Parameters:

query (required): MQL query string to validate

Example:

{
  "query": "CpuUtilization[5m].mean() > 80"
}

4. `get_mql_suggestions`

Get MQL query suggestions and templates for a specific namespace.

Parameters:

namespace (required): OCI namespace to get suggestions for

Example:

{
  "namespace": "oci_computeagent"
}

5. `manage_template_variables`

Manage template variables for dynamic queries.

Actions: list, add, update, remove, refresh, resolve

Example:

{
  "action": "refresh",
  "variableName": "compartment"
}

4. `manage_authentication`

Manage OCI authentication contexts and test connectivity.

Actions: list, test, test_all, refresh, report

Example:

{
  "action": "test_all"
}

5. `query_cross_tenancy`

Query metrics across multiple tenancies for comparison.

Example:

{
  "queries": [
    {
      "tenancyId": "prod",
      "namespace": "oci_computeagent",
      "metricName": "CpuUtilization"
    },
    {
      "tenancyId": "dev",
      "namespace": "oci_computeagent", 
      "metricName": "CpuUtilization"
    }
  ],
  "timeRange": {
    "startTime": "1h"
  }
}

Core Tools

1. `query_oci_metrics`

Query OCI monitoring metrics with Logan MCP compatible timestamps.

Parameters:

namespace (required): OCI namespace (e.g., "oci_computeagent", "oci_lbaas")
metricName (required): Metric to query (e.g., "CpuUtilization", "NetworksBytesIn")
startTime (required): Start time (ISO 8601 or relative like "1h", "24h")
endTime (optional): End time (defaults to now)
compartmentId (optional): Uses default if not provided
dimensions (optional): Metric dimension filters
aggregation (optional): mean, sum, count, max, min, rate (default: mean)
interval (optional): PT1M, PT5M, PT1H, etc. (default: PT1M)

2. `generate_metrics_graph`

Create interactive visualizations for metrics data.

Parameters:

metricQueries (required): Array of metric queries to visualize
graphType (optional): line, bar, scatter, heatmap, pie (default: line)
title (optional): Graph title
includeCorrelation (optional): Generate correlation analysis
ipAddresses (optional): IP addresses for Logan correlation

3. `list_oci_namespaces`

Discover available OCI monitoring namespaces.

4. `list_namespace_metrics`

List available metrics in a specific namespace.

5. `prepare_anomaly_detection_data`

Format metrics data for Data Science MCP server analysis.

6. `get_logan_time_correlation`

Synchronize OCI metrics with Logan MCP timestamps.

7. `test_oci_connection`

Verify OCI connectivity and configuration.

8. `get_common_time_ranges`

Get Logan MCP compatible time ranges and intervals.

📊 Usage Examples

💡 Tip: See for comprehensive OCI MQL query examples and patterns.

Enhanced MQL Queries (v2.0)

Advanced Aggregations

// 95th percentile CPU over 5 minutes
{
  "query": "CpuUtilization[5m].percentile(95)",
  "namespace": "oci_computeagent"
}

// Rate of network bytes over 1 minute  
{
  "query": "rate(NetworksBytesIn[1m])",
  "namespace": "oci_computeagent"
}

// Maximum memory utilization with grouping
{
  "query": "MemoryUtilization[5m].max() by (resourceId)",
  "namespace": "oci_computeagent"
}

Fuzzy Matching and Filtering

// Fuzzy match resources starting with "prod"
{
  "query": "CpuUtilization[5m]{resourceDisplayName =~ \"prod*\"}.mean()",
  "namespace": "oci_computeagent"
}

// Multiple pattern matching
{
  "query": "CpuUtilization[1m]{resourceId in \"id1|id2|id3\"}.mean()",
  "namespace": "oci_computeagent"
}

Alarm Conditions

// CPU threshold alarm
{
  "query": "CpuUtilization[5m].mean() > 80",
  "namespace": "oci_computeagent"
}

// Absence detection
{
  "query": "CpuUtilization[1m].groupBy(resourceId).absent(5m)",
  "namespace": "oci_computeagent"
}

Join Operations

// AND condition for high resource usage
{
  "query": "CpuUtilization[5m].mean() > 80 && MemoryUtilization[5m].mean() > 70",
  "namespace": "oci_computeagent"
}

// OR condition for critical alerts
{
  "query": "CpuUtilization[5m].mean() > 90 || MemoryUtilization[5m].mean() > 95",
  "namespace": "oci_computeagent"
}

Unit Conversion

// Convert milliseconds to seconds
{
  "query": "TotalRequestLatency[1m].mean() / 1000",
  "namespace": "oci_objectstorage"
}

// Calculate total network throughput
{
  "query": "VnicBytesIn[1m].rate() + VnicBytesOut[1m].rate()",
  "namespace": "oci_vcn"
}

Template Variables

// Query with template variable substitution
{
  "query": "$metric[$interval].$aggregation()",
  "namespace": "oci_computeagent",
  "variables": {
    "metric": "CpuUtilization",
    "interval": "5m", 
    "aggregation": "mean"
  }
}

Cross-Tenancy Comparison

{
  "queries": [
    {
      "tenancyId": "production",
      "namespace": "oci_computeagent",
      "metricName": "CpuUtilization",
      "compartmentId": "ocid1.compartment.oc1..prod"
    },
    {
      "tenancyId": "development", 
      "namespace": "oci_computeagent",
      "metricName": "CpuUtilization",
      "compartmentId": "ocid1.compartment.oc1..dev"
    }
  ],
  "timeRange": {
    "startTime": "1h"
  },
  "generateComparison": true
}

Multi-Tenancy Management

// List all configured tenancies
{
  "action": "list"
}

// Test specific tenancy connection
{
  "action": "test",
  "tenancyId": "production"
}

// Test all authentication contexts
{
  "action": "test_all"
}

Basic Metrics Query

// Query CPU utilization for last 24 hours
{
  "namespace": "oci_computeagent",
  "metricName": "CpuUtilization",
  "startTime": "24h",
  "aggregation": "mean",
  "interval": "PT5M"
}

// Enhanced MQL equivalent
{
  "query": "CpuUtilization[5m].mean()",
  "namespace": "oci_computeagent",
  "timeRange": {
    "startTime": "24h"
  }
}

Generate Interactive Graph

// Create line chart with multiple metrics
{
  "metricQueries": [
    {
      "namespace": "oci_computeagent",
      "metricName": "CpuUtilization",
      "startTime": "6h"
    },
    {
      "namespace": "oci_computeagent", 
      "metricName": "MemoryUtilization",
      "startTime": "6h"
    }
  ],
  "graphType": "line",
  "title": "Compute Instance Performance"
}

Correlation Analysis

// Generate correlation heatmap
{
  "metricQueries": [...],
  "graphType": "heatmap",
  "includeCorrelation": true,
  "title": "Service Correlation Analysis"
}

Anomaly Detection Preparation

// Prepare data for ML analysis
{
  "metricQueries": [...],
  "includeContext": true,
  "timeWindow": "7d"
}

🕒 Logan MCP Integration

This server is designed for seamless integration with Logan MCP:

Time Format Compatibility

Timestamps: ISO 8601 UTC format (2024-01-15T10:30:00.000Z)
Time Ranges: Same relative formats (1h, 24h, 7d)
Correlation: Built-in timestamp synchronization

IP Correlation

// Correlate metrics with network events
{
  "metricQueries": [...],
  "ipAddresses": ["10.0.1.100", "192.168.1.50"],
  "graphType": "line"
}

Data Flow for Correlation

Logan MCP → Security events with timestamps and IPs
OCI Metrics MCP → Infrastructure metrics at same time periods
Correlation → Match events with performance anomalies
Data Science MCP → Anomaly detection and predictive analysis

📈 Common OCI Namespaces & Metrics

Compute (`oci_computeagent`)

CpuUtilization - CPU usage percentage
MemoryUtilization - Memory usage percentage
NetworksBytesIn/Out - Network traffic
DiskBytesRead/Written - Disk I/O

Enhanced MQL Examples:

# High CPU alert with fuzzy matching
CpuUtilization[5m]{resourceDisplayName =~ "web*"}.mean() > 80

# Memory usage by availability domain
MemoryUtilization[5m].max() by (availabilityDomain)

# Network throughput calculation
rate(NetworksBytesIn[1m]) + rate(NetworksBytesOut[1m])

# Absence detection for instances
CpuUtilization[1m].groupBy(resourceId).absent(5m)

Load Balancer (`oci_lbaas`)

RequestCount - Number of requests
ResponseTime - Response latency
ActiveConnections - Current connections
HealthyBackendCount - Healthy backends

Enhanced MQL Examples:

# 95th percentile response time
ResponseTime[5m].percentile(95) > 500

# Request rate by backend set
RequestCount[1m].sum() by (backendSetName)

# Health monitoring
HealthyBackendCount[1m].min() < 2

# Load balancer performance ratio
RequestCount[1m].sum() / ActiveConnections[1m].mean()

VCN (`oci_vcn`)

VnicBytesIn/Out - VNIC network traffic
PacketsIn/Out - Packet counts
DroppedPacketsIn/Out - Dropped packets

Enhanced MQL Examples:

# Total network throughput
VnicBytesIn[1m].rate() + VnicBytesOut[1m].rate()

# Dropped packet detection
DroppedPacketsIn[5m].sum() > 100

# Network performance monitoring
(DroppedPacketsIn[5m].sum() / PacketsIn[5m].sum()) * 100 > 1

Database (`oci_database`)

CpuUtilization - Database CPU usage
DatabaseConnections - Active connections
StorageUtilization - Storage usage

Enhanced MQL Examples:

# Database performance monitoring
CpuUtilization[5m].mean() > 75 && DatabaseConnections[1m].count() > 80

# Storage capacity planning
StorageUtilization[1h].max() > 85

# Connection limit monitoring
DatabaseConnections[1m].count() / DatabaseConnectionsMax[1m].max() > 0.8

Object Storage (`oci_objectstorage`)

TotalRequestLatency - Request latency in milliseconds
RequestCount - Number of requests
ErrorCount - Number of errors

Enhanced MQL Examples:

# Convert latency to seconds
TotalRequestLatency[1m].percentile(95) / 1000

# Error rate calculation
(ErrorCount[1m].sum() / RequestCount[1m].sum()) * 100 > 5

# Request monitoring by bucket
RequestCount[1m]{bucketName =~ "backup*"}.sum()

🎨 Graph Types & Visualizations

Line Charts

Perfect for time-series metrics showing trends over time.

Bar Charts

Compare metrics across different resources or time periods.

Scatter Plots

Identify correlations between different metrics.

Heatmaps

Visualize correlation matrices and intensity patterns.

Pie Charts

Show proportional relationships for latest metric values.

🔧 Configuration

Claude Desktop Configuration

{
  "mcpServers": {
    "oci-metrics": {
      "command": "node",
      "args": ["/Users/abirzu/dev/mcp-oci-metrics-server/dist/index.js"],
      "env": {
        "OCI_COMPARTMENT_ID": "ocid1.compartment.oc1..aaaa...",
        "SUPPRESS_LABEL_WARNING": "true"
      }
    }
  }
}

Claude Code Configuration

{
  "oci-metrics": {
    "command": "node",
    "args": ["dist/index.js"],
    "cwd": "/Users/abirzu/dev/mcp-oci-metrics-server",
    "env": {
      "OCI_COMPARTMENT_ID": "ocid1.compartment.oc1..aaaa...",
      "SUPPRESS_LABEL_WARNING": "true"
    }
  }
}

Environment Variables

OCI_COMPARTMENT_ID (required): The OCID of the compartment to query metrics from
SUPPRESS_LABEL_WARNING (optional): Suppress warning labels in output
Region is auto-detected from OCI CLI config (~/.oci/config), defaults to eu-frankfurt-1

🚨 Troubleshooting

Common Issues

"OCI config file not found"

# Ensure OCI CLI is configured
oci setup config

"Failed to query metrics"
- Check compartment ID and permissions
- Verify metric name and namespace exist
- Ensure time range is valid
"Graph generation failed"
- Verify metrics returned data points
- Check if time ranges overlap
- Ensure proper metric query parameters

Debug Mode

# Enable verbose logging
export OCI_DEBUG=true
npm start

Connection Test

# Test OCI connectivity
curl -X POST http://localhost:3001/tools/test_oci_connection \
  -H "Content-Type: application/json" \
  -d '{}'

🧪 Testing

# Run tests
npm test

# Test specific namespace
npm run test -- --grep "monitoring"

# Integration test
node dist/test-integration.js

📚 API Reference

OCI Monitoring API

Based on: https://docs.public.content.oci.oraclecloud.com/en-us/iaas/api/#/en/monitoring/20180401/

Supported Operations

ListMetrics: Discover available metrics
SummarizeMetricsData: Query time-series data
GetMetric: Retrieve metric definitions

🤝 Integration Workflow

With Logan MCP

Query security events from Logan MCP
Extract timestamps and IP addresses
Query corresponding OCI metrics for same time periods
Use get_logan_time_correlation to synchronize timestamps
Generate correlation visualizations

With Data Science MCP

Use prepare_anomaly_detection_data to format metrics
Send prepared data to Data Science MCP
Receive anomaly scores and predictions
Visualize results with annotated graphs

📄 License

MIT License - see file for details.

🙋‍♂️ Support

For issues and questions:

Check OCI CLI configuration: oci setup config
Verify permissions and compartment access
Test connection: Use test_oci_connection tool
Review server logs for detailed error messages

Built for seamless OCI monitoring integration with Logan MCP correlation and Data Science MCP anomaly detection capabilities.

adibirzu/mcp-oci-metrics-server

Enhanced OCI Metrics MCP Server

🆕 Enhanced Features (v2.0)

🏢 Multi-Tenancy Support

🔍 Advanced MQL (Metric Query Language)

📊 Template Variables

🔐 Enhanced Authentication

⚙️ Grafana-Style Datasource Management

✨ Core Features

🚀 Quick Start

1. Clone and Setup

2. Configure Environment

3. Setup OCI CLI

4. Build and Test

5. Configure Claude Desktop

🛠️ Available Tools

Enhanced Tools (v2.0)

1. manage_datasource_config

2. query_mql

3. validate_mql

4. get_mql_suggestions

5. manage_template_variables

4. manage_authentication

5. query_cross_tenancy

Core Tools

1. query_oci_metrics

2. generate_metrics_graph

3. list_oci_namespaces

4. list_namespace_metrics

5. prepare_anomaly_detection_data

6. get_logan_time_correlation

7. test_oci_connection

8. get_common_time_ranges

📊 Usage Examples

Enhanced MQL Queries (v2.0)

Advanced Aggregations

Fuzzy Matching and Filtering

Alarm Conditions

Join Operations

Unit Conversion

Template Variables

Cross-Tenancy Comparison

Multi-Tenancy Management

Basic Metrics Query

Generate Interactive Graph

Correlation Analysis

Anomaly Detection Preparation

🕒 Logan MCP Integration

Time Format Compatibility

IP Correlation

Data Flow for Correlation

📈 Common OCI Namespaces & Metrics

Compute (oci_computeagent)

Load Balancer (oci_lbaas)

VCN (oci_vcn)

Database (oci_database)

Object Storage (oci_objectstorage)

🎨 Graph Types & Visualizations

Line Charts

Bar Charts

Scatter Plots

Heatmaps

Pie Charts

🔧 Configuration

Claude Desktop Configuration

Claude Code Configuration

Environment Variables

🚨 Troubleshooting

Common Issues

Debug Mode

Connection Test

🧪 Testing

📚 API Reference

OCI Monitoring API

Supported Operations

🤝 Integration Workflow

With Logan MCP

With Data Science MCP

📄 License

🙋‍♂️ Support

1. `manage_datasource_config`

2. `query_mql`

3. `validate_mql`

4. `get_mql_suggestions`

5. `manage_template_variables`

4. `manage_authentication`

5. `query_cross_tenancy`

1. `query_oci_metrics`

2. `generate_metrics_graph`

3. `list_oci_namespaces`

4. `list_namespace_metrics`

5. `prepare_anomaly_detection_data`

6. `get_logan_time_correlation`

7. `test_oci_connection`

8. `get_common_time_ranges`

Compute (`oci_computeagent`)

Load Balancer (`oci_lbaas`)

VCN (`oci_vcn`)

Database (`oci_database`)

Object Storage (`oci_objectstorage`)