token-counter-mcp 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# Token Counter MCP
+
+An MCP server that accurately counts and tracks every Claude token — input, output, cache read/write, and planning. Uses the official Anthropic token-counting API for **exact** counts (not estimates).
+
+## Hosted Service — One Command Setup
+
+We run a hosted instance so you don't need your own Anthropic API key or any deployment:
+
+```bash
+claude mcp add --transport sse token-counter https://proud-motivation-production-c4ab.up.railway.app/sse
+```
+
+Restart Claude Code and the tools are ready.
+
+### Interactive Setup (with Dashboard)
+
+For a guided setup that also configures the live dashboard token:
+
+```bash
+npx -y token-counter-mcp --setup
+```
+
+This updates `~/.claude.json` automatically and prints your personal dashboard URL.
+
+---
+
+## Available Tools
+
+| Tool | What it does |
+|------|-------------|
+| `count_tokens` | Exact token count for any text or conversation via Anthropic API |
+| `log_usage` | Record actual token usage after an API call (input, output, cache) |
+| `get_session_stats` | Running totals and USD cost for the current session |
+| `get_usage_history` | Last N usage entries across all sessions |
+| `reset_session` | Zero out session totals (history is preserved) |
+| `estimate_cost` | Calculate USD cost for a given token count without making an API call |
+
+---
+
+## Usage in Claude Code
+
+Once added, ask Claude things like:
+
+```
+How many tokens is this conversation so far?
+Log my last API call: 1500 input, 300 output, claude-opus-4-6
+What's my total spend this session?
+How much would 50k input + 10k output tokens cost on claude-sonnet-4-6?
+Show me my usage history for the last 10 entries.
+Reset my session totals.
+```
+
+---
+
+## Self-Hosted Deployment
+
+Want to run your own instance with your own API key?
+
+### macOS
+
+```bash
+# Install Railway CLI
+brew install railway
+
+# Clone and build
+git clone https://github.com/krishnakantparashar/TokenCounterMCP
+cd TokenCounterMCP
+npm install && npm run build
+
+# Deploy
+railway login
+railway init
+railway up
+railway domain
+
+# Set your Anthropic API key
+railway variables set ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE
+```
+
+### Windows (PowerShell)
+
+```powershell
+# Install Railway CLI (requires Node.js)
+npm install -g @railway/cli
+
+# Clone and build
+git clone https://github.com/krishnakantparashar/TokenCounterMCP
+cd TokenCounterMCP
+npm install
+npm run build
+
+# Deploy
+railway login
+railway init
+railway up
+railway domain
+
+# Set your Anthropic API key
+railway variables set ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE
+```
+
+After deployment, connect with:
+```bash
+claude mcp add --transport sse token-counter https://YOUR-URL.up.railway.app/sse
+```
+
+---
+
+## Local stdio Mode
+
+Runs entirely on your machine. Requires Node.js 18+.
+
+### Quickstart (no clone needed)
+
+```bash
+claude mcp add token-counter -- npx -y token-counter-mcp
+```
+
+That's it. Restart Claude Code — the server starts on demand via `npx`.
+
+### Manual install (if you prefer)
+
+```bash
+git clone https://github.com/krishnakantparashar/TokenCounterMCP
+cd TokenCounterMCP
+npm install && npm run build
+```
+
+Set your API key for exact counts (optional — falls back to ~97–99% accurate local counting without it):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE   # macOS/Linux
+$env:ANTHROPIC_API_KEY="sk-ant-YOUR_KEY_HERE"   # Windows PowerShell
+```
+
+Add to Claude Code:
+
+```bash
+# macOS/Linux
+claude mcp add token-counter -- node "/absolute/path/to/TokenCounterMCP/dist/index.js"
+
+# Windows
+claude mcp add token-counter -- node "C:\path\to\TokenCounterMCP\dist\index.js"
+```
+
+### Local Dashboard
+
+When running in local stdio mode, a live dashboard is available at:
+
+```
+http://localhost:8899
+```
+
+Open it in your browser to see session totals, per-project cost breakdowns, and usage history.
+
+---
+
+## Counting Modes
+
+| Mode | Accuracy | Requires |
+|------|----------|----------|
+| Exact (Anthropic API) | 100% | `ANTHROPIC_API_KEY` set on server |
+| Local approximation | ~97–99% | Nothing — works offline |
+
+The hosted service uses exact counting. Local mode without a key uses `gpt-tokenizer` (cl100k_base BPE) as a fallback.
+
+---
+
+## Supported Models & Pricing
+
+| Model | Input | Output | Cache Read | Cache Write |
+|-------|-------|--------|------------|-------------|
+| `claude-opus-4-6` | $5.00 / 1M | $25.00 / 1M | $0.50 / 1M | $1.25 / 1M |
+| `claude-sonnet-4-6` | $3.00 / 1M | $15.00 / 1M | $0.30 / 1M | $0.75 / 1M |
+| `claude-haiku-4-5` | $1.00 / 1M | $5.00 / 1M | $0.10 / 1M | $0.25 / 1M |
+
+Models not in the table fall back to Sonnet pricing. Versioned model IDs (e.g. `claude-opus-4-6-20260101`) are matched by prefix.
+
+---
+
+## Rate Limits
+
+The hosted service allows **60 requests per minute** per IP. For higher limits, deploy your own instance.
+
+---
+
+## Token Storage (local mode only)
+
+Usage history is stored at `~/.claude/token-counter/` (macOS/Linux) or `%USERPROFILE%\.claude\token-counter\` (Windows):
+
+| File | Contents |
+|------|----------|
+| `session.json` | Current session totals (reset with `reset_session`) |
+| `history.json` | All-time log, capped at 10,000 entries |
+
+The hosted service does not persist your usage data between sessions.

package/dist/costs.d.ts

@@ -0,0 +1,19 @@
+export interface ModelPricing {
+    inputPerMillion: number;
+    outputPerMillion: number;
+    cacheReadPerMillion: number;
+    cacheWritePerMillion: number;
+}
+export declare const MODEL_PRICING: Record<string, ModelPricing>;
+export declare function getPricing(model: string): ModelPricing;
+export interface TokenCost {
+    inputCost: number;
+    outputCost: number;
+    cacheReadCost: number;
+    cacheWriteCost: number;
+    totalCost: number;
+}
+export declare function calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number): TokenCost;
+export declare function formatCost(usd: number): string;
+export declare function formatTokens(n: number): string;
+//# sourceMappingURL=costs.d.ts.map

package/dist/costs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.d.ts","sourceRoot":"","sources":["../src/costs.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAgCtD,CAAC;AASF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAUtD;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,eAAe,SAAI,EACnB,gBAAgB,SAAI,GACnB,SAAS,CAQX;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9C"}

package/dist/costs.js

@@ -0,0 +1,72 @@
+export const MODEL_PRICING = {
+    "claude-opus-4-6": {
+        inputPerMillion: 5.0,
+        outputPerMillion: 25.0,
+        cacheReadPerMillion: 0.5, // 10% of input
+        cacheWritePerMillion: 1.25, // 25% of input
+    },
+    "claude-sonnet-4-6": {
+        inputPerMillion: 3.0,
+        outputPerMillion: 15.0,
+        cacheReadPerMillion: 0.3,
+        cacheWritePerMillion: 0.75,
+    },
+    "claude-haiku-4-5": {
+        inputPerMillion: 1.0,
+        outputPerMillion: 5.0,
+        cacheReadPerMillion: 0.1,
+        cacheWritePerMillion: 0.25,
+    },
+    // Legacy / fallback
+    "claude-opus-4-5": {
+        inputPerMillion: 5.0,
+        outputPerMillion: 25.0,
+        cacheReadPerMillion: 0.5,
+        cacheWritePerMillion: 1.25,
+    },
+    "claude-sonnet-4-5": {
+        inputPerMillion: 3.0,
+        outputPerMillion: 15.0,
+        cacheReadPerMillion: 0.3,
+        cacheWritePerMillion: 0.75,
+    },
+};
+const DEFAULT_PRICING = {
+    inputPerMillion: 3.0,
+    outputPerMillion: 15.0,
+    cacheReadPerMillion: 0.3,
+    cacheWritePerMillion: 0.75,
+};
+export function getPricing(model) {
+    // Try exact match first
+    if (MODEL_PRICING[model])
+        return MODEL_PRICING[model];
+    // Try prefix match (e.g. "claude-opus-4-6-20260101" → "claude-opus-4-6")
+    for (const key of Object.keys(MODEL_PRICING)) {
+        if (model.startsWith(key))
+            return MODEL_PRICING[key];
+    }
+    return DEFAULT_PRICING;
+}
+export function calculateCost(model, inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0) {
+    const pricing = getPricing(model);
+    const inputCost = (inputTokens / 1_000_000) * pricing.inputPerMillion;
+    const outputCost = (outputTokens / 1_000_000) * pricing.outputPerMillion;
+    const cacheReadCost = (cacheReadTokens / 1_000_000) * pricing.cacheReadPerMillion;
+    const cacheWriteCost = (cacheWriteTokens / 1_000_000) * pricing.cacheWritePerMillion;
+    const totalCost = inputCost + outputCost + cacheReadCost + cacheWriteCost;
+    return { inputCost, outputCost, cacheReadCost, cacheWriteCost, totalCost };
+}
+export function formatCost(usd) {
+    if (usd < 0.001)
+        return `$${(usd * 1000).toFixed(4)}m`; // show in milli-dollars
+    return `$${usd.toFixed(6)}`;
+}
+export function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(2)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return `${n}`;
+}
+//# sourceMappingURL=costs.js.map

package/dist/costs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.js","sourceRoot":"","sources":["../src/costs.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}