fathom-token-mcp

MCP server that exposes Fathom's AI cost intelligence as tools for any MCP-compatible client. Estimate tasks, recommend models, check budgets, and manage intent — without leaving your editor.

Quick Start

npx fathom-token-mcp --project-dir .

The server communicates over stdio — it's designed to be launched by an MCP client, not run manually.

Editor Setup

Claude Code

Add to .mcp.json in your project root (auto-created by fathom init):

{
  "mcpServers": {
    "fathom": {
      "command": "npx",
      "args": ["-y", "fathom-token-mcp@latest", "--project-dir", "."]
    }
  }
}

Other Editors

• Cursor
• VS Code
• Windsurf
• Cline

Available Tools

Once connected, 10 tools are available in your MCP client:

| Tool | Description | |------|-------------| | fathom_get_project_intent | Get project purpose, values, constraints, and guardrails from .fathom/intent.yaml | | fathom_estimate_task_cost | Estimate tokens and cost for a task before starting (task type + complexity) | | fathom_recommend_model | Get the best model for a task based on complexity, budget, and history | | fathom_check_budget | Check AI spending: monthly limit, current spend, remaining balance | | fathom_get_project_guardrails | Get resolved security/quality/process guardrails (OWASP, WCAG, HIPAA, etc.) | | fathom_generate_tool_configs | Regenerate editor configs (Claude, Cursor, Copilot, Windsurf) from intent | | fathom_get_feature_registry | Get all tracked features with status, complexity, and estimates | | fathom_list_available_models | List all known models with pricing. Filter by provider or tier | | fathom_get_velocity_metrics | Get development velocity: tokens/hour, average task time, breakdowns | | fathom_get_project_status | Quick project overview: feature progress, budget status, config summary |

Example

Ask your AI assistant:

"Use fathom to estimate the cost of building a user authentication flow at medium complexity"

It calls fathom_estimate_task_cost with taskType: "api-endpoint" and complexity: "M", returning the token estimate, cost projection, and overhead breakdown.

Requirements

• Node.js 20+
• A .fathom/ directory in your project (run npx fathom-cli init to create one)

Part of Fathom

fathom-token-mcp exposes the Fathom intelligence layer via MCP. See the main repo for the full picture.

License

MIT