calcfi-mcp-server

CalcFi's stdio Model Context Protocol server. Exposes 24 personal-finance tools, 10 mesh resources, and 7 prompts to any MCP client (Claude Desktop, Cursor, Continue.dev, Cline, Zed, Codeium).

• 100% free — no paid APIs, no hosting cost
• Brand-stamped responses (citation + freshness + disclaimer on every call)
• YMYL-safe — educational only, not financial advice
• Architecture: docs/specs/strategy/architects/01-mcp-architecture.md

Install

npm (global)

npm install -g calcfi-mcp-server
calcfi-mcp --help

npx (no install)

npx -y calcfi-mcp-server

Register with an MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "calcfi": {
      "command": "npx",
      "args": ["-y", "calcfi-mcp-server"],
      "env": {
        "MCP_ENABLE_AI_INSIGHTS": "false"
      }
    }
  }
}

Restart Claude Desktop. The CalcFi tools should appear in the slash-command picker.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "calcfi": {
      "command": "npx",
      "args": ["-y", "calcfi-mcp-server"]
    }
  }
}

Continue.dev

In your .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "calcfi-mcp-server"]
        }
      }
    ]
  }
}

Cline (VS Code extension)

Open the Cline MCP settings panel and add:

{
  "calcfi": {
    "command": "npx",
    "args": ["-y", "calcfi-mcp-server"]
  }
}

Tools (24)

| Category | Tools | |---|---| | Atomic math (8) | mortgage_payment, paycheck_takehome, debt_payoff_avalanche, debt_payoff_snowball, retirement_projection, cd_calculator, auto_loan, cost_of_living_compare | | Mesh exposure (10) | get_dataset_doi, get_code_provenance, get_methodology, get_press_coverage, list_example_notebooks, list_interactive_apps, list_embeddable_codepens, list_observable_notebooks, get_author_profile, list_datahub_datasets | | Citation (1) | cite_this | | Scenario (2) | save_scenario, cross_analyze (URL-only by design) | | Email (2) | email_full_report, subscribe_freshness_digest | | Composite redirect (1) | get_money_analysis_score (URL-only) |

Resources (10)

calcfi://datasets/index, calcfi://datasets/changelog, calcfi://methodology/v2, calcfi://author/profile, calcfi://doi/dataset, calcfi://swhid/code, calcfi://press/coverage, calcfi://datahub/index, calcfi://huggingface/spaces, calcfi://schemas/calc-index.

Prompts (7)

compare_paycheck_by_state, cite_calcfi_dataset, cross_analyze_money_health, summarize_freshness, find_canonical_calc_url, mortgage_affordability_full_picture, weekly_money_digest.

Env-var kill switches

| Var | Default | Effect | |---|---|---| | MCP_KILL_SWITCH | false | Global off-switch — every tool call returns a 503-style error. | | MCP_ENABLE_AI_INSIGHTS | false | MUST stay false. Defense-in-depth gate against OpenAI-billed tool exposure. | | MCP_ENABLE_EMAIL_TOOLS | true | Disable email_full_report + subscribe_freshness_digest. | | MCP_ENABLE_SCENARIO_SAVES | true | Disable save_scenario + cross_analyze. | | MCP_ENABLE_MESH_TOOLS | true | Disable the 10 mesh-exposure tools. | | MCP_MAX_CONCURRENT | 100 | HTTP-shim concurrency cap (informational here; enforced in the shim package). | | CALCFI_MCP_VERSION | from package.json | Override reported version. | | CALCFI_MCP_COMMIT | dev | Override reported git commit. |

Brand-stamp envelope

Every tool result is wrapped in:

{
  "result": { /* tool payload */ },
  "meta": {
    "verified_as_of": "2026-05-29",
    "source": "...",
    "methodology_url": "https://calcfi.app/methodology",
    "cite_url": "https://calcfi.app/...",
    "disclaimer": "Educational only, not financial advice.",
    "license": "CC-BY-4.0"
  },
  "cross_sell": {
    "save_scenario_url": "https://calcfi.app/my-numbers?...",
    "see_cross_analysis_at": "https://calcfi.app/my-numbers",
    "related_calcs": ["..."]
  },
  "freshness": {
    "data_age_hours": 0.5,
    "next_refresh_at": "2026-05-29T13:00:00Z"
  }
}

Development

npm install
npm run build
node bin/calcfi-mcp.js

Then drive it with @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector node bin/calcfi-mcp.js

License

MIT. Data is CC-BY-4.0. Citation appreciated: see cite_this tool.