Cloudzero MCP

🚀 CloudZero Model Context Protocol (MCP) Server

Engage in conversations about CloudZero's cloud cost data using Large Language Models (LLMs).

Ask questions about your cost data, such as visualizing monthly differences:

🚀 Quick Start

The CloudZero MCP Server enables users to interact with cloud cost data through LLMs. After proper configuration, users can query cost - related information and view visualizations.

✨ Features

• Data Interaction: Communicate with CloudZero's cloud cost data via LLMs.
• Specific Tools: Implement CloudZero - specific tools like get_costs, get_dimensions, list_budgets, and list_insights.
• JSON - RPC 2.0: Use JSON - RPC 2.0 for request and response handling.

🔧 Technical Details

How It Works

It uses the CloudZero v2 API and Model Context Protocol MCP.

graph LR
    %%{init: {'theme':'neutral'}}%%
    %% Define nodes
    A[MCP Host]
    B[Local MCP Server]
    C[CloudZero API]
    D[(Cloud Cost Data)]

    %% Define connections
    A -->|JSON-RPC 2.0| B
    B -->|HTTP/JSON| C
    C <--> D

    subgraph CloudZero_SaaS
    C
    D
    end

    subgraph Background_process
    B
    end

    subgraph Claude_Desktop
    A
    end

    subgraph Local_Machine
    Claude_Desktop
    Background_process
    end

    %% Define styles
    classDef client padding:10px
    classDef server padding:10px
    classDef api padding:10px
    classDef db padding:10px

    %% Apply styles
    class A client
    class B server
    class C api
    class D db

Once the MCP server is configured in Claude Desktop, it starts as a background process upon startup. Claude Desktop, acting as the MCP host, sends an initiatize request to the MCP server. The server responds with its capabilities, including prompts and tools for tool invocation.

The server implements several CloudZero - specific tools:

• get_costs: Retrieve billing data from start_date to end_date.
• get_dimensions: Obtain billing dimensions.
• list_budgets: List budgets.
• list_insights: List insights.

The MCP protocol uses JSON - RPC 2.0 for requests and responses.

📦 Installation

Prerequisites

1. Install Claude Desktop.
2. Install uv.

Setup Project Dependencies

uv init
uv sync

Generate API Key

Generate your CloudZero API key.

Configure Environment Variables

Edit the .env file as follows:

CLOUDZERO_API_KEY=YOUR_SECRET_KEY

Install the MCP Server

To install the MCP server in Claude Desktop:

uv run mcp install server.py

Configure Claude Desktop

Edit your claude_desktop_config.json to set the correct uv command path and update your USERNAME as shown below.

This configuration file can be found at Settings > Developer > Edit Config in Claude Desktop.

    "CloudZero": {
      "command": "/Users/USERNAME/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/Users/USERNAME/workspace/open_source/cloudzero-mcp/server.py"
      ]
    }

Restart Claude Desktop

Restart Claude Desktop. When the desktop starts, it will launch the server process in the background. You may encounter errors and can drill down into the logs to identify issues.

If there are no errors, try asking "What cloud billing tools are available" to view the list.

For more information, refer to the Claude Desktop MCP documentation.

💻 Usage Examples

Basic Usage

After the server is set up and running, you can ask questions about cloud cost data in Claude Desktop. For example, you can ask "What are the available cloud billing tools" to get a list of tools.

Advanced Usage

If you want to retrieve specific cost data, you can use the get_costs tool. For example, you can ask the LLM to call the get_costs tool to get billing data from a specific start date to an end date.

📚 Documentation

For more detailed information, please refer to the following documentation:

• CloudZero v2 API
• Model Context Protocol
• Claude Desktop MCP documentation

🔧 Debugging

To debug, you can run the MCP development server with an interactive GUI for inspection:

uv run mcp dev server.py

This is very useful for troubleshooting errors in the code without constantly restarting Claude Desktop.