Metadata-Version: 2.4
Name: caphound-mcp
Version: 0.1.0
Summary: CapHound MCP server — stdio bridge that lets Claude Desktop, Cursor, and other MCP clients query your CapHound AI cost data.
Author: CapHound
License-Expression: MIT
Project-URL: Homepage, https://caphound.ai
Project-URL: Repository, https://github.com/CapHound/caphound
Keywords: mcp,model-context-protocol,claude,finops,ai-cost,caphound,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0

# caphound-mcp

**Ask your AI cost data from Claude Desktop, Cursor, or any MCP client — Python edition.**

`caphound-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) stdio server that exposes CapHound's analytics, budgets, forecasts, and savings recommendations as tools your AI assistant can call directly. Functionally identical to the [`@caphound/mcp`](https://www.npmjs.com/package/@caphound/mcp) Node package — use whichever fits your toolchain.

```
You:    What's causing my AI spend this week?
Claude: [calls caphound.get_top_cost_drivers]
        Your top cost drivers (last 7 days):
         1. chat-summarizer — $812.40 (61% of feature spend, 14,200 requests)
         2. semantic-search — $231.15 (17%, 89,000 requests)
         3. doc-extract     — $144.20 (11%, 3,400 requests)
        ...
```

## Quick start

### Claude Desktop (Python-centric users — uvx)

If you have [uv](https://docs.astral.sh/uv/) installed, add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "caphound": {
      "command": "uvx",
      "args": ["caphound-mcp"],
      "env": {
        "CAPHOUND_API_KEY": "warden_live_xxxxxxxxxxxx"
      }
    }
  }
}
```

### Plain pip install

```bash
pip install caphound-mcp
```

Then point your MCP client at the `caphound-mcp` entry point:

```json
{
  "mcpServers": {
    "caphound": {
      "command": "caphound-mcp",
      "env": {
        "CAPHOUND_API_KEY": "warden_live_xxxxxxxxxxxx"
      }
    }
  }
}
```

(On some setups you may need the absolute path to the `caphound-mcp` script — find it with `which caphound-mcp` / `where caphound-mcp`.)

### Get your API key

1. Log in to [control.caphound.ai](https://control.caphound.ai).
2. **Settings → API Keys → Create new key.**
3. Copy the `warden_live_...` value. It's only shown once.

## Available tools

| Tool | What it answers |
|---|---|
| `get_spend_summary` | *"How much have I spent?"* — totals + model + feature breakdown for a date range. |
| `get_top_cost_drivers` | *"What's causing my spend?"* — ranked features / customers / models / teams. |
| `get_budget_status` | *"How are my budgets doing?"* — utilisation, alert threshold, runway days. |
| `get_forecast` | *"How much will I spend this month?"* — projection, daily burn rate, budget exhaustion ETA. |
| `get_unit_economics` | *"Which customers / features are unprofitable?"* — cost per 1K requests + month-over-month change. |
| `get_savings_opportunities` | *"What can I do to save money today?"* — projected overrun, model-downgrade candidates, concentration risk. |
| `get_recent_decisions` | *"What did CapHound block or downgrade?"* — enforcement audit trail. |
| `get_active_alerts` | *"Should I be worried right now?"* — unresolved spend anomalies and budget breaches. |
| `get_provider_health` | *"Are OpenAI / Anthropic up?"* — 5-minute rolling error rates. |

All tools are **read-only**. CapHound's MCP server never mutates state.

## Configuration

| Env var | Required | Default | Description |
|---|---|---|---|
| `CAPHOUND_API_KEY` | yes | — | Bearer token (`warden_live_…` or `warden_test_…`). |
| `CAPHOUND_API_BASE` | no | `https://api.caphound.ai` | Override for self-hosted or staging deployments. |

## Example prompts

- *"What's my AI spend today and last week, compared?"*
- *"Which feature's cost is growing fastest month-over-month?"*
- *"My budget is set at $5K — am I going to blow it?"*
- *"Show me what got enforced in the last hour."*
- *"What's the cheapest model swap that would save me real money?"*

## How it works

`caphound-mcp` is a tiny stdio bridge:

```
Claude Desktop  ⇆  stdio  ⇆  caphound-mcp  ⇆  HTTPS  ⇆  api.caphound.ai
                                                            ↓
                                                     Your workspace data
```

The bridge forwards JSON-RPC 2.0 messages between your local MCP client and CapHound's HTTP MCP endpoint, attaching your API key as a bearer token. No data is cached or stored locally.

## Troubleshooting

**"CAPHOUND_API_KEY is not set"** — check the `env` block in your client config; restart the client after editing.

**Tools don't appear in Claude Desktop** — confirm the config file path, verify it's valid JSON, then quit and reopen Claude (menu bar → Quit, not just close window).

**`401 unauthorized`** — your API key is invalid, revoked, or from a different workspace. Generate a fresh one in **Settings → API Keys**.

**Transport errors** — verify network egress to `api.caphound.ai`; if you're self-hosted, set `CAPHOUND_API_BASE` to your deployment URL.

## Privacy

CapHound's MCP server returns *aggregated cost data only* — never prompt or response content. The CapHound product never stores LLM content in any tier; see [the privacy commitment](https://caphound.ai/privacy).

## License

MIT
