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

npm install
npm run build

Set your key:

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

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.:

{
  "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.