bhuv1436/CloudZeroMCPServer

CloudZero MCP Server

A production-ready Model Context Protocol (MCP) server for integrating with CloudZero billing APIs. This server provides advanced cost analysis tools through a standardized MCP interface, enabling sophisticated cloud cost management and FinOps workflows.

Features

• 🔍 Billing Costs Retrieval: Get detailed cost data with filtering options
• 🔒 Secure Authentication: Environment variable-based API key management
• ✅ Input Validation: Comprehensive validation with user-friendly error messages
• 📊 Flexible Querying: Support for different granularities, groupings, and cost types

Prerequisites

• Node.js 18+
• CloudZero account with API access
• CloudZero API key

Installation

1. Clone or download this project

2. Install dependencies:

   npm install
   

3. Install CloudZero SDK:

   npx api install "@cloudzero/v2.0.0-main#1dpb61pmea4h1ld"
   

4. Set up environment variables:

   cp .env.example .env
   

   Edit .env file and add your CloudZero API key:

   CLOUDZERO_API_KEY=your_actual_api_key_here
   

5. Build the project:

   npm run build
   

Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

Available Tools

get_billing_costs

Retrieve billing costs from CloudZero with filtering options.

Parameters:

• start_date (required): Start date in ISO format (e.g., 2025-01-01T00:00:00Z)
• end_date (required): End date in ISO format (e.g., 2025-01-31T23:59:59Z)
• granularity (optional): Time granularity - daily, weekly, or monthly (default: daily)
• group_by (optional): Dimension to group costs by (default: Service)
• cost_type (optional): Type of cost calculation - real_cost, amortized_cost, or blended_cost (default: real_cost)

Example usage in MCP client:

{
  "tool": "get_billing_costs",
  "arguments": {
    "start_date": "2025-01-01T00:00:00Z",
    "end_date": "2025-01-31T23:59:59Z",
    "granularity": "daily",
    "group_by": "Service",
    "cost_type": "real_cost"
  }
}

Error Handling

The server provides user-friendly error messages for common issues:

• Missing or invalid API key configuration
• Incorrect date formats
• Invalid parameter values
• CloudZero API connectivity issues

Configuration

Environment Variables

Project Structure

├── src/
│   ├── index.ts                 # Main MCP server
│   ├── cloudzero-client.ts      # CloudZero API client
│   └── tools/
│       └── billing-costs.ts     # Billing costs tool implementation
├── .env.example                 # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

Development

Building

npm run build

Running in development mode

npm run dev

License

MIT