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

Variable	Description	Default
OCI_COMPARTMENT_ID	Required. OCID of the OCI Compartment.	N/A
OCI_LOG_GROUP_ID	Required. OCID of the OCI Log Group.	N/A
OCI_LOG_ID	Required. OCID of the OCI Custom Log.	N/A
OCI_CONFIG_PROFILE	Profile name in your OCI config file.	DEFAULT
OCI_CONFIG_FILE	Path to your OCI config file.	~/.oci/config

License

MIT