OCI Load Balancer Log MCP Server

A Model Context Protocol (MCP) server for querying and analyzing Oracle Cloud Infrastructure (OCI) Load Balancer custom logs. This server allows LLMs to directly search through traffic logs by country, IP, location, and perform aggregated traffic analytics.

Features

• Search by Country: Filter logs by country name or ISO country code.
• Search by IP: Look up specific IP addresses or CIDR-style prefixes.
• Geographic Search: Find traffic originating from specific latitude/longitude bounding boxes.
• Traffic Analytics: Get top talkers, country distribution, and protocol statistics.
• Zero Hardcoding: Fully configurable via environment variables.

Prerequisites

1. OCI CLI Configured: You must have a valid OCI configuration file (usually at ~/.oci/config).
2. Environment Variables: You need the OCIDs for your compartment, log group, and the specific custom log.

Installation & Usage

Running via uvx

You can run the MCP server directly from GitHub without manual installation using uvx:

export OCI_COMPARTMENT_ID="ocid1.tenancy.oc1..xxxx"
export OCI_LOG_GROUP_ID="ocid1.loggroup.oc1.xxxx"
export OCI_LOG_ID="ocid1.log.oc1.xxxx"

uvx --from git+https://github.com/mamorett/oci_lb_log_custom_mcp.git oci-lb-logs

Configuration for MCP Hosts (e.g., Claude Desktop)

Add the following entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "oci-lb-logs": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mamorett/oci_lb_log_custom_mcp.git",
        "oci-lb-logs"
      ],
      "env": {
        "OCI_COMPARTMENT_ID": "ocid1.tenancy.oc1..your_compartment_ocid",
        "OCI_LOG_GROUP_ID": "ocid1.loggroup.oc1.your_region.your_log_group_ocid",
        "OCI_LOG_ID": "ocid1.log.oc1.your_region.your_custom_log_ocid",
        "OCI_CONFIG_PROFILE": "DEFAULT",
        "OCI_CONFIG_FILE": "/absolute/path/to/your/.oci/config"
      }
    }
  }
}

Tools Exposed

IP Tools

#### list_unique_ips List all unique IP addresses seen in the logs, deduplicated and sorted by request count. Optionally filter by country to get all IPs from a specific origin.

• time_range (string): Time window to search (e.g., "24h", "7d"). Default: "24h".
• limit (integer): Max raw log entries to scan. Default: 500.
• country (string, optional): Filter by full country name (e.g., "Germany").
• country_code (string, optional): Filter by ISO country code (e.g., "DE").

Returns a list of `IPSummary` objects: ip, request_count, country, country_code, city, isp, protocols.

#### get_top_ips Return the top N IP addresses ranked by request count over the given time range. Samples a large window of logs to find the noisiest sources.

• time_range (string): Time window to analyze. Default: "24h".
• top_n (integer): Number of top IPs to return. Default: 20.
• sample_limit (integer): Max raw log entries to scan. Default: 5000.

Returns a list of `IPSummary` objects sorted by request_count descending.

#### get_ips_by_country Return unique IP addresses grouped by country, with per-country request totals and unique IP counts. Useful for a full breakdown of all traffic sources by origin.

• time_range (string): Time window to analyze. Default: "24h".
• limit (integer): Max raw log entries to scan. Default: 2000.

Returns a list of `IPsByCountry` objects sorted by total_requests descending. Each entry contains: country, country_code, total_requests, unique_ip_count, and a full ips list of `IPSummary`.

Search / Filter Tools

#### search_logs_by_country Search raw log entries by country name or country code.

• country (string, optional): Full country name (e.g., "United States").
• country_code (string, optional): ISO country code (e.g., "US").
• time_range (string): Time window to search. Default: "24h".
• limit (integer): Maximum number of entries to return. Default: 100.

#### search_logs_by_ip Search raw log entries by a specific IP address or an IP range prefix.

• ip_address (string, optional): Exact IP address.
• ip_range (string, optional): IP prefix (e.g., "192.168").
• time_range (string): Time window to search. Default: "24h".
• limit (integer): Maximum number of entries to return. Default: 100.

#### search_logs_by_location Search raw log entries within a geographic bounding box.

• lat_min, lat_max, lon_min, lon_max (float): Bounding box coordinates.
• time_range (string): Time window to search. Default: "24h".
• limit (integer): Maximum number of entries to return. Default: 100.

Analytics Tools

#### get_traffic_analytics Get aggregated traffic statistics (counts only, no IPs). Use the IP tools above if you need actual addresses.

• group_by (string): Field to aggregate by ("country", "city", "isp", or "protocol"). Default: "country".
• time_range (string): Time window to analyze. Default: "24h".
• limit (integer): Number of raw log entries to sample. Default: 1000.

Environment Variables

License

MIT