tokencast MCP server

<!-- mcp-name: io.github.krulewis/tokencast -->

tokencast

Pre-execution cost estimation for LLM agent workflows. Get a cost estimate before running any agent task, then let tokencast learn from actuals to improve accuracy over time.

Available as a Claude Code plugin (recommended — one command delivers everything) or as an MCP server for Cursor, VS Code + Copilot, and Windsurf.

Installation

Claude Code (Recommended)

Install tokencast as a Claude Code plugin — delivers the MCP server, calibration hooks, and estimation skill in two commands:

/plugin marketplace add krulewis/tokencast
/plugin install tokencast@tokencast

The first command registers the tokencast marketplace. The second installs the plugin from it.

Prerequisites: uv must be installed for the MCP server to function.

Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

This delivers:

• MCP server (estimatecost, getcalibrationstatus, getcosthistory, reportsession, reportstepcost)
• Calibration hooks (auto-learning at session end, mid-session cost warnings, agent timeline tracking)
• SKILL.md (estimation algorithm auto-trigger after plans)

Calibration data is stored in ~/.tokencast/calibration/ (global across projects, preserved on uninstall).

Scope options: --scope user (recommended — installs globally for all projects) or --scope project (per-project only).

Other IDEs (MCP Server)

Install the package:

pip install tokencast

Or with uvx (no install required — runs directly from PyPI):

uvx tokencast

Configure your IDE — replace /path/to/your/project with your actual project path in the config snippets below.

Cursor

Create or update .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "tokencast": {
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

VS Code + GitHub Copilot

Create or update .vscode/mcp.json in your project root:

{
  "servers": {
    "tokencast": {
      "type": "stdio",
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "tokencast": {
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Full config examples are in docs/ide-configs/.

Available tools

Once configured, tokencast exposes five MCP tools in your IDE:

Example — estimate before starting work:

Estimate the cost for: size=M, files=8, complexity=high

Example — report actuals after finishing:

Report session cost: actual_cost=4.20

Telemetry

tokencast includes opt-out anonymous usage telemetry. It is on by default — data is collected unless you explicitly disable it.

Shortened. The full README is on GitHub.