token-calculator-suite

🧮 Token Calculator Suite

Unified token calculation system for Claude Chat, Cowork, and Claude Code.

Reusable, open-source library for estimating Claude token consumption across three Anthropic platforms. Built with modularity, accuracy, and privacy in mind.

✨ Features:

• 📊 Accurate token estimation (±18% with exact data)
• 🔄 Single source of truth (shared core library)
• 🌍 Multi-platform: Chat, Cowork, Claude Code
• 🛡️ Privacy-first (Option C consent model)
• 📦 Production-ready TypeScript
• 📚 Fully documented with examples

---

📦 What's included

token-calculator-suite/
├── packages/
│   ├── core/                    ← Shared calculation logic
│   ├── chat-skill/              ← Claude.ai skill
│   ├── cowork-plugin/           ← Claude Cowork plugin
│   └── claude-code-mcp/         ← Claude Code CLI tool
├── README.md                    ← This file
└── package.json                 ← Monorepo config

---

🚀 Quick Start

For Chat (claude.ai)

Installation: Copy packages/chat-skill/SKILL.md to your skills folder.

Usage:

/tokens

Features:

• ✅ Calculates tokens in current conversation
• ✅ Opción C: Asks permission before using personal data
• ✅ Accuracy: ±18% with exact data, ±22-30% without
• ✅ Real-time context usage tracking

---

For Cowork

Installation:

1. Zip packages/cowork-plugin/ as token-calculator.zip
2. In Cowork: Customize > Plugins > Upload > Select zip

Usage:

/tokens:analyze        # Analyze current file
/tokens:report         # Generate token usage report

Features:

• ✅ Analyzes PDFs, DOCX, images, code files
• ✅ Generates batch reports for multiple files
• ✅ Suggests optimization opportunities
• ✅ Exports as CSV or table

---

For Claude Code

This MCP server integrates token calculation directly into Claude Code, allowing you to estimate token usage and API costs while working on projects.

Prerequisites

• Node.js 18.0.0 or higher - Required for MCP server operation
• Yarn 4.0.0+ - Used for dependency management in this monorepo
• Git - Required to clone the repository

Installation Steps

1. Clone the repository

   git clone https://github.com/token-calculator-suite/token-calculator-suite.git
   cd token-calculator-suite
   

2. Install dependencies

   yarn install
   

   This installs all workspace dependencies. The installation creates a node_modules directory and sets up workspace links.

3. Build the MCP server

   yarn workspace @token-calculator/claude-code-mcp build
   

   This compiles the TypeScript code into JavaScript in the dist directory. You should see output indicating successful compilation with no errors.

4. Verify the build was successful

   ls -la packages/claude-code-mcp/dist/
   

   You should see mcp-server.js in this directory.

5. Configure Claude Code

   Edit (or create) ~/.claude/settings.json and add the MCP server configuration:

   {
     "mcpServers": {
       "token-calculator": {
         "command": "node",
         "args": ["/full/path/to/token-calculator-suite/packages/claude-code-mcp/dist/mcp-server.js"],
         "type": "stdio"
       }
     }
   }
   

   Important: Replace /full/path/to/token-calculator-suite with the absolute full path to your cloned repository. You can find the full path by running pwd in the repository directory.

6. Restart Claude Code

   Close and reopen Claude Code. The token calculator MCP will be automatically loaded.

Troubleshooting

If the MCP server fails to start:

• Check Node.js version: Run node --version and ensure it's >= 18.0.0
• Verify the build: Ensure packages/claude-code-mcp/dist/mcp-server.js exists and is not empty
• Check the path: Ensure the args path in settings.json uses the absolute full path (starting with /) to the mcp-server.js file
• Clear cache: If you had build errors before, try yarn clean followed by yarn install && yarn build
• Check logs: Examine Claude Code's console output (View → Output in Claude Code) for detailed error messages

Features

Once installed, the token calculator MCP provides:

• ✅ Real-time token estimation for text
• ✅ File analysis (PDF, DOCX, images, code)
• ✅ API cost calculation for Claude models
• ✅ Multi-language support
• ✅ Batch processing support

---

📊 How It Works

Core Library (packages/core/)