# CostHawk MCP Server

Official MCP server for [CostHawk](https://costhawk.ai) - AI API cost monitoring and optimization platform.

> **Early Alpha** - CostHawk is currently in early alpha testing. [Join the waitlist](https://costhawk.ai) 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

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

This opens your browser, asks you to approve the device code, then writes MCP config automatically for Claude Code, Codex CLI, and Gemini CLI.
By default, this creates one **hybrid token** with scopes:
- `mcp:read`
- `mcp:write`
- `otel:ingest`

### Codex Desktop usage tracking (non-CLI path)

If you use Codex Desktop and do not want to set up each local CLI tool manually, use the Codex-specific setup path:

```bash
npm exec --yes costhawk@latest -- setup codex-desktop
```

This preflights the local runtime and writable Codex config, opens CostHawk browser login, then configures only Codex Desktop usage tracking. It does not write Claude Code, Gemini CLI, Cursor, or OpenCode config.

### Manual Token Mode (Fallback)

```bash
# 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](https://costhawk.ai/dashboard/settings) 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:

```bash
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):

```bash
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:

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

This writes CostHawk MCP config for you after browser approval, including `~/.codex/config.toml` for Codex CLI.

Manual token setup is still available:

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

Non-interactive:

```bash
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`:

```jsonc
{
  "$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:

```bash
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:

```bash
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:

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

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

```bash
npm exec --yes costhawk@latest -- --what-we-read
```

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

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

## Available Tools

### Usage Tracking

| Tool | Description |
|------|-------------|
| `costhawk_get_company_brain_onboarding` | Get the workspace Company Brain destination and per-project sharing policies before writing learnings |
| `costhawk_get_usage_summary` | Get usage and costs over a time period (by provider/model) |
| `costhawk_get_usage_by_tag` | Get usage grouped by attribution fields and custom metadata (`project`, `feature`, `team`, `environment`, `user_id`, etc.) |
| `costhawk_detect_anomalies` | Check for cost anomalies and unusual usage patterns |

`costhawk_get_company_brain_onboarding` is the policy gate for Company Brain writes. Private projects must not submit shared learnings. Project memory projects can keep local/project-scoped memory. Company Brain projects can submit allowed entry types using the configured review mode.

`costhawk_get_usage_by_tag` has two data sources:
- Standard attribution fields like `feature`, `project`, `team`, and `environment` can come from wrapped-key or scoped API key attribution.
- Arbitrary custom tag keys only appear when you send request metadata through the proxy, such as `costhawk_metadata.feature` or `costhawk_metadata.user_id`.

### 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 |
| `brain status` | Show Company Brain sharing policy for the current repo/workspace |
| `setup codex-desktop` | Configure Codex Desktop usage tracking only |
| `--setup-codex-desktop` | Alias for `setup codex-desktop` |
| `--setup` | Configure Claude Code, Codex CLI, and Gemini CLI MCP settings |
| `--codex` / `--no-codex` | Include or skip Codex CLI config at `~/.codex/config.toml` |
| `--opencode` / `--no-opencode` | Include or skip OpenCode config |

Company Brain CLI example:

```bash
costhawk brain status --org-slug acme --git-repo github.com/acme/app
```

## 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](https://costhawk.ai) and wait for approval
2. **Install via Browser Login**: Run `npm exec --yes costhawk@latest -- --login`
3. **Fallback (Manual Token)**: Create token at Settings → Developer and install with `COSTHAWK_API_KEY`
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.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

## Links

- [Join Waitlist](https://costhawk.ai)
- [Documentation](https://docs.costhawk.ai)
- [npm Package](https://www.npmjs.com/package/costhawk)

## License

MIT