Anthropic Billing MCP Server

An MCP (Model Context Protocol) server for retrieving Anthropic billing and cost report data.

Features

• Retrieve detailed cost reports from Anthropic's billing API
• Support for time-based filtering and grouping
• Daily cost summaries with USD conversion
• Support for beta API features
• Pagination support for large datasets
• Type-safe with Zod validation

Installation

Option 1: Using claude mcp add (Recommended)

# Add the MCP server from GitHub
claude mcp add anthropic-billing https://github.com/your-username/anthropic-billing-mcp

# Set your API key
claude mcp env anthropic-billing ANTHROPIC_API_KEY=your_api_key_here

Option 2: Manual Installation

git clone https://github.com/your-username/anthropic-billing-mcp
cd anthropic-billing-mcp
npm install
npm run build

Setup

1. Get your Anthropic Admin API key from https://platform.claude.com/settings/admin-keys
   • Note: Regular API keys from console.anthropic.com will not work for billing endpoints
   • You need an Admin API key with billing access permissions
2. If using claude mcp add, set the environment variable:

   claude mcp env anthropic-billing ANTHROPIC_API_KEY=your_api_key_here
   

3. If installing manually, set the environment variable:

   export ANTHROPIC_API_KEY=your_api_key_here
   

Usage

With claude mcp add

After installation, the server will be automatically configured and available in Claude Desktop.

Manual Configuration

Add to your MCP configuration (e.g., in Claude Desktop config):

{
  "mcpServers": {
    "anthropic-billing": {
      "command": "node",
      "args": ["/path/to/anthropic-billing-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

get_cost_report

Retrieve raw cost report data from Anthropic's API.

Parameters:

• starting_at (required): RFC 3339 timestamp for start of time range
• ending_at (optional): RFC 3339 timestamp for end of time range
• bucket_width (optional): Time granularity ("1d" only)
• group_by (optional): Array of grouping options ["workspace_id", "description"]
• limit (optional): Maximum number of time buckets to return
• page (optional): Page token for pagination
• beta_headers (optional): Array of beta feature headers

Example:

{
  "starting_at": "2024-01-01T00:00:00Z",
  "ending_at": "2024-01-31T23:59:59Z",
  "group_by": ["description"],
  "beta_headers": ["fast-mode-2026-02-01"]
}

get_daily_costs_summary

Get a formatted summary of daily costs with USD conversion.

Parameters:

• start_date (required): Start date in YYYY-MM-DD format
• end_date (optional): End date in YYYY-MM-DD format (defaults to today)
• group_by_workspace (optional): Whether to group by workspace (default: false)
• group_by_description (optional): Whether to group by description (default: false)
• beta_headers (optional): Array of beta feature headers

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "group_by_description": true
}

Demo: Real-World Usage for Budget Management

This MCP server enables powerful budget management and cost analysis workflows. Here's a real-world example of using it to create a comprehensive burn down analysis.

Scenario: Trading Profit vs API Costs

A trader made $1,000 profit in March 2026 and wanted to track their Anthropic API costs against this budget to ensure profitable AI-assisted trading decisions.

Live Cost Analysis (March 7, 2026)

Using the MCP server's get_cost_report tool, we retrieved actual spending data:

📊 Executive Summary
- Trading Profit This Month: $1,000.00
- Current API Costs: $91.05
- Remaining Budget: $908.95
- Days Elapsed: 7 of 31 (22.6%)
- Budget Utilization: 9.1%

📈 Key Performance Metrics
- Daily Average Cost: $13.01 ($91.05 ÷ 7 days)
- Projected Monthly Cost: $403.31 (at current rate)
- Target Daily Budget: $32.26 (1000 ÷ 31 days)
- API ROI: 1,098% ($1000 profit vs $91.05 cost)

Budget Burn Rate Visualization

Week 1  [███████████████████████████▓▓▓▓▓] $91.05 (28% of weekly target)
Week 2  [█████████████████████████████████] $91.05 (projected)
Week 3  [█████████████████████████████████] $91.05 (projected)
Week 4  [█████████████████████████████████] $91.05 (projected)
Week 5  [█████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] $39.11 (projected)

Risk Assessment & Strategic Insights

🟢 Current Status: LOW-MODERATE Risk

• Tracking 59% below daily budget target
• Cost efficiency: 9.1¢ per dollar of trading profit
• Room to scale usage 2.5x while staying in budget
• Outstanding ROI demonstrates profitable AI integration

MCP Integration Benefits

1. Real-Time Budget Monitoring

# Get current month costs instantly
get_daily_costs_summary start_date=2026-03-01

2. Automated Burn Rate Calculations

The MCP server enables programmatic cost analysis without manual API calls:

• Daily average spending calculations
• Projected monthly costs based on current usage
• Budget variance tracking
• ROI analysis against business metrics

3. Multi-Scenario Planning

# Scenario 1: Current pace → $403.31 monthly (40.3% of budget)
# Scenario 2: 25% increase → $504.14 monthly (50.4% of budget)
# Scenario 3: 50% increase → $604.97 monthly (60.5% of budget)

4. Integration with Business Logic

The MCP server allows seamless integration with:

• Trading algorithms that factor in API costs
• Automated budget alerts and thresholds
• Cost-per-decision optimization
• Dynamic usage scaling based on profitability

Sample Budget Management Workflow

# Pseudo-code showing typical workflow
def optimize_trading_strategy():
    # Get real-time costs via MCP
    current_costs = get_daily_costs_summary()
    daily_avg = current_costs.total / days_elapsed

    # Calculate remaining budget runway
    remaining_budget = trading_profit - current_costs.total
    safe_daily_spend = remaining_budget / days_remaining

    # Adjust API usage based on cost efficiency
    if daily_avg < safe_daily_spend * 0.8:
        return "SCALE_UP"  # Opportunity to use more AI
    elif daily_avg > safe_daily_spend * 1.2:
        return "SCALE_DOWN"  # Risk of budget overrun
    else:
        return "MAINTAIN"  # Optimal pace

This real-world example demonstrates how the MCP server transforms basic billing data into actionable business intelligence, enabling data-driven decisions about AI investment and usage optimization.

📋 Full Analysis Available: See examples/trading-budget-burndown.md for the complete burn down analysis with weekly projections, risk assessments, and KPI tracking.

API Response Structure

Cost Items

Each cost item includes:

• amount: Cost in cents as decimal string
• currency: Currency code (always "USD")
• description: Description of the cost item
• model: Model name used
• cost_type: Type of cost ("tokens", "web_search", "code_execution")
• token_type: Token type for token costs
• service_tier: Service tier ("standard", "batch")
• context_window: Input context window used
• workspace_id: Associated workspace ID
• inference_geo: Inference geography used
• speed: Speed tier (with beta header)

Daily Summary Format

{
  "summary": [
    {
      "date": "2024-01-01",
      "total_cost_cents": 1234,
      "total_cost_usd": "12.34",
      "items": [...]
    }
  ],
  "total_cost_cents": 50000,
  "total_cost_usd": "500.00",
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "has_more": false,
  "next_page": null
}

Development

Build

npm run build

Run in Development

npm run dev

Test

npm test

Environment Variables

• ANTHROPIC_API_KEY: Your Anthropic Admin API key from platform.claude.com/settings/admin-keys (required)
  • Regular API keys will not work - billing endpoints require Admin API keys

Error Handling

The server includes comprehensive error handling for:

• Missing API keys
• Invalid API responses
• Network errors
• Validation errors
• API rate limits

All errors are returned with descriptive messages to help with debugging.

License

MIT