JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 328
  • Score
    100M100P100Q109665F
  • License MIT

MCP server for CostHawk - AI API cost monitoring and optimization with Claude Code tracking

Package Exports

  • costhawk
  • costhawk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (costhawk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 optional auto-sync (NEW in v1.3.0)
  • Codex local usage tracking with optional auto-sync (NEW in v1.3.1)
  • 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@latest

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

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

Auto-sync is off by default. Enable it by setting COSTHAWK_AUTO_SYNC=true in your MCP configuration.

Make sure you’re running the latest MCP build before debugging tool lists:

npx -y costhawk@latest --self-test

This prints:

  • the MCP version
  • the full tool list (including Codex tools)
  • basic local checks (Claude/Codex directories, API key presence)

If Claude Code doesn’t show the tools, restart it after installing and re-run:

npx -y costhawk@latest --tools

To see exactly which local directories and sample files are read:

npx -y costhawk@latest --what-we-read

To include the git commit hash in --self-test (and --version), build with:

COSTHAWK_GIT_SHA=$(git rev-parse --short HEAD) npm run build

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 (Optional Auto-Sync)

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 (Opt-in): Set COSTHAWK_AUTO_SYNC=true to automatically sync your Claude Code usage to CostHawk every 15 minutes while running. Requires COSTHAWK_API_KEY.

  • 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.

Codex Local Tracking (Beta)

These tools parse your local Codex session logs from ~/.codex/sessions/ to track token usage by type.

Optional Auto-Sync: Set COSTHAWK_AUTO_SYNC=true to enable auto-sync, and optionally set COSTHAWK_CODEX_AUTO_SYNC=false to disable Codex auto-sync.

Tool Description
costhawk_sync_codex_usage Sync local Codex usage to CostHawk dashboard
costhawk_get_local_codex_usage View local Codex usage offline with token breakdown
costhawk_list_codex_sessions List available Codex sessions

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)
COSTHAWK_DEBUG No Log API requests (set to true)
COSTHAWK_AUTO_SYNC No Enable auto-sync (set to true)
COSTHAWK_CODEX_AUTO_SYNC No Disable Codex auto-sync (set to false)

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

CLI Flags

Flag Description
--version / -v Print the MCP server version and exit
--tools Print the registered tool names and exit
--self-test Print version + tool list + local env checks and exit
--what-we-read Print local directories and sample files read by the MCP

Privacy & Trust

CostHawk’s MCP server is designed to be local-first and transparent:

  • Local parsing only: We read ~/.claude/projects/ and ~/.codex/sessions/ locally to compute usage.
  • No conversation content sent: Only token totals and metadata are transmitted.
  • Dry-run mode: Use dryRun=true in costhawk_sync_claude_code_usage or costhawk_sync_codex_usage to preview payloads without uploading.
  • Payload previews: Use previewLimit to see the first N sessions that would be uploaded.
  • File list visibility: Use includeFileList=true to see which local files were read.
  • Auto-sync is opt-in: Enabled only when you set COSTHAWK_AUTO_SYNC=true.
  • Debug logging: Set COSTHAWK_DEBUG=true to log API requests.

Example dry run (no upload):

Use costhawk_sync_claude_code_usage with dryRun=true includeFileList=true previewLimit=3

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.3.6 (February 2026)

Trust & Transparency

  • New: Dry-run support for Claude + Codex sync tools
  • New: includeFileList and payload previews for sync tools
  • New: --what-we-read CLI flag to show local paths and samples
  • New: COSTHAWK_DEBUG=true to log API requests
  • New: COSTHAWK_GIT_SHA support for version/diagnostics
  • Fixed: Commit hash is now baked into published builds for --self-test
  • Updated: Auto-sync is opt-in (COSTHAWK_AUTO_SYNC=true)

v1.3.2 (February 2026)

CLI Quality-of-Life

  • New: --version flag for fast version checks
  • New: --tools flag to list MCP tools without starting the server
  • New: --self-test flag to show tool list + local environment checks
  • Updated: Recommend npx -y costhawk@latest to avoid stale global binaries

v1.3.1 (February 2026)

Codex Local Tracking (Beta)

  • New: costhawk_sync_codex_usage - Sync local Codex session usage to CostHawk
  • New: costhawk_get_local_codex_usage - View Codex usage offline with token breakdown
  • New: costhawk_list_codex_sessions - List available local Codex sessions
  • New: Optional Codex auto-sync (COSTHAWK_CODEX_AUTO_SYNC=true)

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

License

MIT