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.

State of the Project

We are in active development and currently in early access.

As of v1.1.4, 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

If you installed a version prior to v1.1.4, please update to get the latest features:

npm update -g costhawk

To use CostHawk, you must first join the waitlist at costhawk.ai. We're onboarding new users weekly.

Setup

1. Build the Server

cd /path/to/costhawk-mcp-server
npm install
npm run build

2. Get Your API Key

Log into CostHawk dashboard
Go to Settings → API Keys
Create a new key for MCP access
Copy the key (you'll only see it once)

3. Configure Claude Desktop

Edit your Claude Desktop config file:

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

Add the CostHawk server:

{
  "mcpServers": {
    "costhawk": {
      "command": "node",
      "args": ["/absolute/path/to/costhawk-mcp-server/dist/index.js"],
      "env": {
        "COSTHAWK_API_KEY": "your-api-key-here",
        "COSTHAWK_API_URL": "https://costhawk.ai"
      }
    }
  }
}

4. Restart Claude Desktop

Quit and reopen Claude Desktop to load the new MCP server.

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 API key
`COSTHAWK_API_URL`	No	`https://costhawk.ai`	API base URL (for self-hosted)

Development

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Start production server
npm start

Troubleshooting

"Tool not found" errors:

Ensure Claude Desktop was restarted after config changes
Check the path to dist/index.js is absolute and correct

"Authentication failed" errors:

Verify your API key is correct
Check the key is active in CostHawk dashboard

"Connection refused" errors:

Ensure COSTHAWK_API_URL is accessible
Check your network/firewall settings

License

MIT