# deepseek-costs-mcp

MCP server for tracking DeepSeek API costs, built on the official DeepSeek API.

## Scope

DeepSeek's official API does **not** expose historical usage/cost analytics
(no per-key spend, no per-model token history, no time-series). The only
billing-related data it exposes is:

- `GET /user/balance` — current account balance (account-level, not per-key)
- `GET /models` — list of models available to your key

This server exposes exactly those two endpoints as MCP tools, plus a local
calculator (`deepseek_estimate_cost`) that converts token counts you already
have (e.g. from a chat completion's `usage` field) into an estimated USD cost,
using a static snapshot of DeepSeek's published pricing page. It does **not**
proxy or log your completions — it has no way to see which key spent what
unless DeepSeek adds that to their API.

## Tools

| Tool | Calls | Notes |
|---|---|---|
| `deepseek_get_balance` | `GET /user/balance` | Total / granted / topped-up balance, per currency |
| `deepseek_list_models` | `GET /models` | Models available to the configured key |
| `deepseek_estimate_cost` | (local calculator) | `{ model, cacheHitInputTokens?, cacheMissInputTokens?, outputTokens? }` → cost breakdown in USD |

Pricing snapshot: `src/pricing.ts` (dated 2026-07-14). Re-check
https://api-docs.deepseek.com/quick_start/pricing/ periodically — DeepSeek can
change prices without a versioned API.

## Setup

```bash
npm install
npm run build
```

Set your key:

```bash
cp .env.example .env
# edit .env and set DEEPSEEK_API_KEY
```

The server reads `DEEPSEEK_API_KEY` from the process environment (not
dotenv-loaded automatically) — whatever MCP client launches it must inject
that variable.

## Running standalone

```bash
DEEPSEEK_API_KEY=sk-... node dist/index.js
```

It speaks MCP over stdio.

## Connecting to Hermes Agent

Point Hermes Agent's MCP client config at the built entry point as a stdio
server, e.g.:

```json
{
  "mcpServers": {
    "deepseek-costs": {
      "command": "node",
      "args": [
        "<path>/deepseek-costs/dist/index.js"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-..."
      }
    }
  }
}
```

Adjust the config key/path to whatever format Hermes Agent expects for stdio
MCP servers. After connecting, the three tools above should show up in its
tool list.