CostHawk MCP Server

Official MCP server for CostHawk - AI API cost monitoring and optimization platform.

Early Alpha - CostHawk is currently in early alpha testing. Join the waitlist to get early access.

Overview

CostHawk helps teams track, analyze, and optimize their AI API spending across providers like Anthropic, OpenAI, and Google.

Key Features:

• Real-time usage tracking and cost analytics
• Claude Code local usage tracking with auto-sync (NEW in v1.3.0)
• Savings analysis for flat-rate subscriptions (Claude Pro/Max, OpenAI Pro)
• Budget alerts and anomaly detection
• Webhook notifications (Slack, Discord, PagerDuty)

Quick Install

# Global installation (all projects)
claude mcp add -s user -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE costhawk -- npx -y costhawk

# Project-specific installation
claude mcp add -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE costhawk -- npx -y costhawk

Get your access token from Settings → Developer in your CostHawk dashboard (requires approved account).

Available Tools

Usage Tracking

| Tool | Description | |------|-------------| | costhawk_get_usage_summary | Get usage and costs over a time period (by provider/model) | | costhawk_get_usage_by_tag | Get usage grouped by custom tags (user_id, feature, etc.) | | costhawk_detect_anomalies | Check for cost anomalies and unusual usage patterns |

Claude Code Local Tracking (Auto-Sync in v1.2.1)

These tools parse your local Claude Code transcripts from ~/.claude/projects/ to track token usage - including the 4 token types Claude Code uses.

Auto-Sync (NEW in v1.3.0): When COSTHAWK_API_KEY is configured, the MCP server automatically syncs your Claude Code usage to CostHawk every 15 minutes while running. No manual sync needed!

• input_tokens - Regular input
• output_tokens - Regular output
• cache_creation_input_tokens - Writing to prompt cache
• cache_read_input_tokens - Reading from cache (10x cheaper!)

| Tool | Description | |------|-------------| | costhawk_sync_claude_code_usage | Sync local usage to CostHawk dashboard for savings analysis | | costhawk_get_local_claude_code_usage | View local usage offline with cost breakdown | | costhawk_list_claude_code_sessions | List available Claude Code sessions |

Example: Check local usage offline

Use costhawk_get_local_claude_code_usage with subscriptionPlan="max_5x"

This shows your token usage, costs at retail rates, and whether you're saving money vs your subscription.

Savings Analysis

| Tool | Description | |------|-------------| | costhawk_get_savings | Compare retail costs vs subscription costs | | costhawk_get_savings_breakdown | Per-model breakdown of usage and costs | | costhawk_list_subscriptions | List your active flat-rate subscriptions |

Pricing & Alerts

| Tool | Description | |------|-------------| | costhawk_get_model_pricing | Get current AI model pricing (input/output per 1M tokens) | | costhawk_list_alerts | List budget warnings, cost spikes, and anomaly alerts |

Webhooks

| Tool | Description | |------|-------------| | costhawk_list_webhooks | List configured webhook endpoints | | costhawk_create_webhook | Create webhook for Slack, Discord, Teams, PagerDuty |

Claude Code Token Types Explained

Claude Code uses caching extensively, which significantly affects your costs:

| Token Type | Description | Sonnet 4 Pricing | |------------|-------------|------------------| | Input | Regular input tokens | $3/1M | | Output | Regular output tokens | $15/1M | | Cache Write | Writing to prompt cache | $3.75/1M | | Cache Read | Reading from cache | $0.30/1M (10x cheaper!) |

The cache read savings are significant - CostHawk tracks all 4 types to give you accurate cost calculations.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | COSTHAWK_API_KEY | Yes* | Your CostHawk API token | | COSTHAWK_API_URL | No | API base URL (defaults to https://costhawk.ai) |

*Required for most tools. Local Claude Code tools work offline without an API key.

Getting Started

1. Get Early Access: Join the waitlist and wait for approval
2. Create API Token: Go to Settings → Developer → Create Token
3. Install MCP Server: Use the quick install command above
4. Start Tracking: Use the tools in Claude Code or Claude Desktop

Example Workflows

Check if your Claude Max subscription is worth it

1. costhawk_list_claude_code_sessions (see what's available)
2. costhawk_get_local_claude_code_usage with subscriptionPlan="max_5x"
3. Review the savings breakdown

Sync usage to dashboard for team visibility

1. costhawk_sync_claude_code_usage (uploads to CostHawk)
2. View detailed analytics at costhawk.ai/dashboard

Set up cost spike alerts

1. costhawk_create_webhook with type="slack" and events=["cost_spike", "budget_alert"]
2. Get notified when costs exceed thresholds

Changelog

v1.2.1 (January 2026)

Auto-Sync - Automatic background syncing

• New: Auto-sync Claude Code usage every 15 minutes while MCP server is running
• New: Initial sync 30 seconds after server starts
• New: Graceful shutdown handling for sync cleanup
• Requires COSTHAWK_API_KEY to be configured for auto-sync

v1.2.0 (January 2026)

Claude Code Local Tracking - Major new feature release

• New: costhawk_sync_claude_code_usage - Sync local Claude Code transcripts to CostHawk
• New: costhawk_get_local_claude_code_usage - View usage offline with cost breakdown
• New: costhawk_list_claude_code_sessions - List available local sessions
• New: Full support for all 4 Claude Code token types (input, output, cache write, cache read)
• New: Offline cost calculation with embedded pricing
• New: Savings comparison vs Claude Pro/Max subscriptions

v1.1.x

• Savings analysis tools (costhawk_get_savings, costhawk_get_savings_breakdown)
• Subscription management (costhawk_list_subscriptions)
• Webhook support for Slack, Discord, Teams, PagerDuty
• Usage tracking and anomaly detection

v1.0.x

• Initial release
• Basic usage summary and cost tracking
• Model pricing lookup
• Alert notifications

Links

• Join Waitlist
• Documentation
• npm Package

License

MIT