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

Model Context Protocol (MCP) server that enables AI assistants like Claude to query your CostHawk data — track your spend, see your stats, and monitor your AI API costs directly from the command line.

State of the Project

We are in active development and currently in early access.

As of v1.1.8, the following features are live:

Usage summary and cost tracking across providers
Savings calculations for flat-rate subscriptions (Claude Max, OpenAI Pro, etc.)
Anomaly detection and cost spike alerts
Webhook integrations (Slack, Discord, Teams, PagerDuty)
Model pricing lookup with context window info

Versions prior to v1.1.4 were non-functional early builds. If you installed an earlier version, please update:

npm update -g costhawk

Getting Started

Step 1: Join the Waitlist

You must first sign up at costhawk.ai to use this package.

We're in early access and onboarding new users weekly. Join the waitlist and we'll notify you when your account is ready.

Step 2: Get Your Access Token

Once approved:

Log into your CostHawk dashboard
Go to Settings → Developer → Create Token
Copy the token (you'll only see it once)

Step 3: Add to Claude Code

Quick install (recommended):

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

# Or for current project only
claude mcp add -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE costhawk -- npx -y costhawk

Replace YOUR_TOKEN_HERE with your access token from Step 2.

Or configure manually by adding to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["-y", "costhawk"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE"
      }
    }
  }
}

Then restart Claude Code.

Step 4: For Claude Desktop (Optional)

If using Claude Desktop instead of Claude Code, edit your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["-y", "costhawk"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE"
      }
    }
  }
}

Then restart Claude Desktop.

Available Tools

Tool	Description
`costhawk_get_usage_summary`	Get usage and cost summary for a date range
`costhawk_get_usage_by_tag`	Break down costs by metadata tags (project, environment, etc.)
`costhawk_detect_anomalies`	Find cost spikes and unusual activity patterns
`costhawk_list_webhooks`	List your configured alert webhooks
`costhawk_create_webhook`	Set up new webhooks for Slack, Discord, Teams, or custom URLs
`costhawk_get_model_pricing`	Look up current model pricing by provider
`costhawk_list_alerts`	View alerts and notifications
`costhawk_get_savings`	Show savings vs retail pricing for flat-rate subscriptions
`costhawk_list_subscriptions`	List active flat-rate subscriptions
`costhawk_get_savings_breakdown`	Show per-model usage and retail cost breakdown

Example Prompts

Once configured, you can ask Claude:

"What's my AI API usage this month?"
"Show me costs broken down by project tag"
"Are there any cost anomalies I should know about?"
"What's the current pricing for Claude Opus?"
"Create a Slack webhook for budget alerts"
"List my unread alerts"
"Show my savings vs retail this month"
"List my flat-rate subscriptions"
"Break down my savings by model"

Environment Variables

Variable	Required	Default	Description
`COSTHAWK_API_KEY`	Yes	-	Your CostHawk access token
`COSTHAWK_API_URL`	No	`https://costhawk.ai`	API base URL (for self-hosted)

Troubleshooting

"Tool not found" errors:

Ensure Claude was restarted after config changes
Verify the config file syntax is valid JSON

"Authentication failed" errors:

Verify your access token is correct
Check the token is active in CostHawk dashboard (Settings → Developer)
Make sure you've been approved from the waitlist

"Connection refused" errors:

Ensure COSTHAWK_API_URL is accessible
Check your network/firewall settings

License

MIT