OCI MCP Server

Instructions

Get cost breakdown by compartment for a tenancy.

Args:
    tenant_id: OCID of the tenancy
    time_usage_started: Start time in ISO format (YYYY-MM-DD)
    time_usage_ended: End time in ISO format (YYYY-MM-DD)

Returns:
    List of costs grouped by compartment with total cost per compartment

Implementation Reference

• mcp_server_oci/tools/cost.py:121-170 (handler)

  Core handler function that executes the tool logic: queries OCI Usage API for usage data grouped by compartmentName, aggregates total costs per compartment, and returns the breakdown.

  def get_cost_by_compartment(usage_api_client: oci.usage_api.UsageapiClient,
                              tenant_id: str,
                              time_usage_started: str,
                              time_usage_ended: str) -> List[Dict[str, Any]]:
      """
      Get cost breakdown by compartment.
  
      Args:
          usage_api_client: OCI UsageApi client
          tenant_id: OCID of the tenancy
          time_usage_started: Start time in ISO format (YYYY-MM-DD)
          time_usage_ended: End time in ISO format (YYYY-MM-DD)
  
      Returns:
          List of costs grouped by compartment
      """
      try:
          request_summarized_usages_details = oci.usage_api.models.RequestSummarizedUsagesDetails(
              tenant_id=tenant_id,
              time_usage_started=time_usage_started,
              time_usage_ended=time_usage_ended,
              granularity="DAILY",
              group_by=["compartmentName"]
          )
  
          usage_response = oci.pagination.list_call_get_all_results(
              usage_api_client.request_summarized_usages,
              request_summarized_usages_details=request_summarized_usages_details
          )
  
          # Aggregate by compartment
          compartment_costs = {}
          for item in usage_response.data.items:
              compartment = item.compartment_name
              if compartment not in compartment_costs:
                  compartment_costs[compartment] = {
                      "compartment_name": compartment,
                      "compartment_id": item.compartment_id,
                      "total_cost": 0.0,
                      "currency": item.currency,
                  }
              compartment_costs[compartment]["total_cost"] += float(item.computed_amount) if item.computed_amount else 0.0
  
          result = list(compartment_costs.values())
          logger.info(f"Retrieved cost breakdown for {len(result)} compartments")
          return result
  
      except Exception as e:
          logger.exception(f"Error getting cost by compartment: {e}")
          raise

• mcp_server_oci/mcp_server.py:1540-1558 (registration)

  MCP tool registration with @mcp.tool and wrapper function that invokes the core handler using the initialized OCI usage_api client.

  @mcp.tool(name="get_cost_by_compartment")
  @mcp_tool_wrapper(
      start_msg="Getting cost breakdown by compartment...",
      error_prefix="Error getting cost by compartment"
  )
  async def mcp_get_cost_by_compartment(ctx: Context, tenant_id: str, time_usage_started: str,
                                        time_usage_ended: str) -> List[Dict[str, Any]]:
      """
      Get cost breakdown by compartment for a tenancy.
  
      Args:
          tenant_id: OCID of the tenancy
          time_usage_started: Start time in ISO format (YYYY-MM-DD)
          time_usage_ended: End time in ISO format (YYYY-MM-DD)
  
      Returns:
          List of costs grouped by compartment with total cost per compartment
      """
      return get_cost_by_compartment(oci_clients["usage_api"], tenant_id, time_usage_started, time_usage_ended)