agent-cost-mcp

# agent-cost-mcp

MCP server that tracks AI agent token usage and spending in real time. Budget alerts, per-task cost breakdown, visual dashboard, daily/weekly/monthly reports.

Works with any MCP client: **Claude Code, Cursor, Windsurf, Codex, Cursor CLI**, and more.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-orange.svg)](https://modelcontextprotocol.io)

![Dashboard](docs/AgentCost_dashboard.png)

![Activity Log](docs/AgentCost_activity.png)

## Why?

Every developer using AI agents worries about spending. Most tools don't tell you what each message costs until the bill arrives.

This MCP server tracks it in real time — per message, per model, per day. Set a budget, get alerts, see exactly where your money goes.

## Features

- **Visual dashboard** — dark-themed web UI with spending charts, budget gauges, and activity log
- **Per-message cost logging** — see what each AI interaction costs instantly
- **Budget alerts** — warns when approaching daily/monthly limits
- **Cost reports** — today, this week, this month, all time
- **Model breakdown** — donut chart showing which model eats your budget
- **Spending trends** — 14-day bar chart with color-coded spending
- **15+ models supported** — Cursor, GPT, Cursor, Cursor, Llama
- **Estimate before running** — check cost before expensive tasks
- **Local storage** — all data stays on your machine (`~/.agent-cost-mcp/`)
- **Auto-refresh** — dashboard updates every 30 seconds

## Quick Start

### 1. Install

```bash
pip install agent-cost-mcp
```

Or with uv:
```bash
uv pip install agent-cost-mcp
```

### 2. Add to your AI tool

**Claude Code** — add to `~/.cursor/settings.json`:
```json
{
  "mcpServers": {
    "agent-cost": {
      "command": "agent-cost-mcp"
    }
  }
}
```

**Cursor** — add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "agen