costhawk

v1.5.11

Published

3 days ago

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

0High
0Medium
0Low

costhawktma

mcp model-context-protocol costhawk ai llm cost-monitoring openai anthropic claude claude-code token-tracking

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:

Comprehensive LLM pricing for 120+ models across 14 providers (NEW in v1.4.0)
Tool pricing for web search, code interpreter, image generation, etc. (NEW in v1.4.0)
Real-time usage tracking and cost analytics
Claude Code local usage tracking with optional auto-sync
Codex local usage tracking with optional auto-sync
Savings analysis for flat-rate subscriptions (Claude Pro/Max, OpenAI Pro)
Budget alerts and anomaly detection
Webhook notifications (Slack, Discord, PagerDuty)

Quick Install

Recommended: Browser Login + Auto-Setup

npm exec --yes costhawk@latest -- --login

This opens your browser, asks you to approve the device code, then writes MCP config automatically. By default, this creates one hybrid token with scopes:

mcp:read
mcp:write
otel:ingest

Manual Token Mode (Fallback)

# Global installation (all projects)
claude mcp add -s user -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE costhawk -- npm exec --yes costhawk@latest

# Project-specific installation
claude mcp add -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE costhawk -- npm exec --yes 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.

Windows note: If claude mcp add fails on Windows, use the built-in --setup command below (it avoids CLI flag parsing issues).

One-line auto-sync setup (recommended)

This installs the MCP and enables auto-sync for both Claude Code + Codex:

claude mcp add -s user \\
  -e COSTHAWK_API_KEY=YOUR_KEY \\
  -e COSTHAWK_AUTO_SYNC=true \\
  costhawk -- npm exec --yes costhawk@latest

Claude-only auto-sync (disable Codex):

claude mcp add -s user \\
  -e COSTHAWK_API_KEY=YOUR_KEY \\
  -e COSTHAWK_AUTO_SYNC=true \\
  -e COSTHAWK_CODEX_AUTO_SYNC=false \\
  costhawk -- npm exec --yes costhawk@latest

If you only run claude mcp add ... without env vars, the MCP installs but auto-sync stays off.

Windows-friendly setup (no `claude mcp add`)

On some Windows setups, claude mcp add doesn’t pass flags correctly. Use the built-in setup:

npm exec --yes costhawk@latest -- --login

This writes CostHawk MCP config for you after browser approval.

Manual token setup is still available:

npm exec --yes costhawk@latest -- --setup

Non-interactive:

npm exec --yes costhawk@latest -- --setup --api-key YOUR_KEY --auto-sync --codex-sync

OpenCode setup (opencode.ai)

OpenCode reads MCP servers from your OpenCode config. Global config lives at:

~/.config/opencode/opencode.json

Add a CostHawk MCP entry under mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "costhawk": {
      "type": "local",
      "command": ["npx", "--yes", "costhawk@latest"],
      "enabled": true,
      "environment": {
        "COSTHAWK_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Restart OpenCode after saving the config.

Note: Local usage parsing and auto-sync currently read Claude Code (~/.claude/projects) and OpenAI Codex CLI (~/.codex/sessions) logs. OpenCode does not expose local session logs yet, so auto-sync only applies if you also use Claude Code or Codex CLI on the same machine.

Prefer a guided setup? Run:

npm exec --yes costhawk@latest -- --setup --opencode --no-claude

Quick Verify (Recommended)

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

npm exec --yes 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:

npm exec --yes costhawk@latest -- --tools

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

npm exec --yes 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 | |------|-------------| | --login | Start browser/device login flow (recommended) | | --no-setup | With --login, skip writing MCP config files | | --open / --no-open | With --login, control browser auto-open behavior | | --client-name | Optional device label shown on approval page | | --scopes | Optional comma-separated scopes for login token (default: mcp:read,mcp:write,otel:ingest) | | --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 | | --setup | Configure Claude Code MCP settings (cross-platform) |

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

Get Early Access: Join the waitlist and wait for approval
Install via Browser Login: Run npm exec --yes costhawk@latest -- --login
Fallback (Manual Token): Create token at Settings → Developer and install with COSTHAWK_API_KEY
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.4.1 (February 2026)

Patch fixes

Fixed: --setup --opencode now supports JSONC files with comments and trailing commas
Fixed: Setup/config handling reliability improvements

v1.4.0 (February 2026)

Comprehensive LLM & Tool Pricing

New: 120+ LLM models with pricing across 14 providers
New: Tool/feature pricing (web search, code interpreter, image generation, etc.)
Providers: OpenAI, Anthropic, Google, Mistral, Meta, Cohere, DeepSeek, Groq, Perplexity, xAI/Grok, Together, AWS Bedrock, Azure OpenAI
OpenAI models: GPT-5.2, GPT-5.1, GPT-5, GPT-4o, GPT-4.1, o-series (o1, o3, o4)
Anthropic models: Claude 4.5, Claude 4.1, Claude 4, Claude 3.5, Claude 3
Google models: Gemini 3, Gemini 2.5, Gemini 2.0, Gemini 1.5
Tool pricing: Web search, code interpreter, DALL-E, Whisper, Imagen, embeddings, and more

v1.3.9 (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
New: --setup command to configure Claude Code MCP settings
Updated: Setup prompts now ask Claude and Codex separately
Fixed: Setup now writes to all known Claude config files (Windows + macOS + Linux)
Fixed: npm exec examples use -- --setup so flags reach the MCP
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 npm exec --yes costhawk@latest to avoid stale global binaries

v1.3.10 (February 2026)

Maintenance

Bug fixes and stability improvements

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