calcfi-mcp-server

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.