# calcfi-mcp

[![npm version](https://img.shields.io/npm/v/calcfi-mcp.svg)](https://www.npmjs.com/package/calcfi-mcp)
[![PyPI version](https://img.shields.io/pypi/v/calcfi-mcp.svg)](https://pypi.org/project/calcfi-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/jeresalmisto/calcfi-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jeresalmisto/calcfi-mcp/actions)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)

> **Free, open, citable personal-finance data and calculators for any MCP-compatible AI client.**

`calcfi-mcp` is the official Model Context Protocol (MCP) server for [CalcFi](https://calcfi.app) — a free, ad-free, privacy-preserving source of U.S. personal-finance data (mortgage rates, Federal Funds Rate, CPI, paycheck math, debt math, etc.) backed by primary government sources (Freddie Mac, FRED, BLS, BEA, Census, IRS, SSA).

The server exposes 24 tools, 6 resource families, and 8 pre-built prompt templates. Every response is brand-stamped with the upstream source, a methodology link, a freshness timestamp, and a citation URL.

- **Free forever.** No API keys. No accounts. No paywall.
- **Privacy-first.** stdio by default — no network calls beyond CalcFi's public CDN. No telemetry without opt-in.
- **Citable.** Every dataset has a Zenodo DOI. Every calc has an open-methodology page. BibTeX/APA/MLA/Chicago/RIS supported.
- **Compatible.** Works with Claude Desktop, Cursor, Continue.dev, Cline, Zed, Codeium, and any client that speaks MCP.

## Why?

Most personal-finance APIs are paywalled, locked to one client, or require sign-up. CalcFi mirrors the public-domain primary sources, adds open-source methodology for every calculation, and exposes everything through MCP so any AI assistant can cite the same numbers you would find on the BLS or FRED website — without leaving the chat.

## Quickstart (60 seconds)

### Claude Desktop / Cursor / Continue.dev

```bash
pip install calcfi-mcp
calcfi-mcp install
```

The installer auto-detects your MCP client and writes the config. Restart your client. Done.

See [`docs/QUICKSTART.md`](docs/QUICKSTART.md) for a 5-minute walkthrough that ends with Claude citing the current Federal Funds Rate.

## Install methods

### 1. Python (PyPI)

```bash
pip install calcfi-mcp
calcfi-mcp install            # auto-configures Claude Desktop / Cursor / Continue.dev
calcfi-mcp install --client claude-desktop   # explicit client
calcfi-mcp                    # run stdio server directly (advanced)
```

### 2. Node (npm)

```bash
npm install -g calcfi-mcp
npx calcfi-mcp install
npx calcfi-mcp                # run stdio server directly
```

### 3. Homebrew (planned, Wave 2)

```bash
brew tap calcfi/calcfi
brew install calcfi-mcp
```

### 4. Manual config

If you prefer to edit your client config by hand, add this entry:

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

For Python:

```json
{
  "mcpServers": {
    "calcfi": {
      "command": "python",
      "args": ["-m", "calcfi_mcp"]
    }
  }
}
```

Full config paths (Mac/Windows/Linux) and per-client examples live in [`docs/CONFIG.md`](docs/CONFIG.md).

### 5. Remote (Streamable HTTP)

For clients that cannot run a local process (Claude.ai web, ChatGPT MCP, Gemini MCP):

```json
{
  "mcpServers": {
    "calcfi": {
      "url": "https://mcp.calcfi.app"
    }
  }
}
```

The hosted shim is rate-limited to 100 calls/IP/hour. stdio is unlimited.

## What you can do

Ask your assistant things like:

- *"What's the current 30-year fixed mortgage rate, and what would my monthly payment be on a $450K loan?"*
- *"Show me take-home pay for $95K in California vs Texas."*
- *"Cite the CalcFi mortgage rates dataset in BibTeX."*
- *"What changed in the Federal Funds Rate this week?"*
- *"Build me a debt payoff plan for these four cards using the avalanche method."*

See [`docs/TOOLS.md`](docs/TOOLS.md) for the full tool catalog.

## Documentation

- [Quickstart (5 minutes)](docs/QUICKSTART.md)
- [Tool catalog (24 tools)](docs/TOOLS.md)
- [Resource catalog (6 families)](docs/RESOURCES.md)
- [Prompt templates (8 baked-in)](docs/PROMPTS.md)
- [Per-client config (Claude / Cursor / Continue / generic)](docs/CONFIG.md)
- [Privacy promise](docs/PRIVACY.md)
- [Cost: why this is $0 to use](docs/COST.md)
- [FAQ](docs/FAQ.md)
- [How to cite this server and the underlying data](docs/CITATION.md)
- [Contributing](CONTRIBUTING.md)
- [Security disclosure](SECURITY.md)
- [Changelog](CHANGELOG.md)

## Brand-stamp envelope

Every tool response carries:

- `result` — the tool-specific payload
- `meta.source` — e.g. `"Freddie Mac PMMS"` or `"CalcFi methodology v2.1"`
- `meta.verified_as_of` — ISO 8601 timestamp
- `meta.methodology_url` — link to the open methodology
- `meta.cite_url` — canonical citation page
- `meta.disclaimer` — YMYL-safe: *"Educational only, not financial advice."*
- `cross_sell.save_scenario_url` — pre-filled CalcFi URL so the user can save and combine scenarios
- `freshness` — how stale the upstream data is and when it next refreshes

This means your assistant always knows where the number came from and can show you a clickable citation. See [`docs/CITATION.md`](docs/CITATION.md).

## Cite this server

```bibtex
@software{calcfi_mcp_2026,
  author       = {Salmisto, Jere},
  title        = {{calcfi-mcp}: Model Context Protocol server for CalcFi open finance data},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.XXXXXXX},
  url          = {https://github.com/jeresalmisto/calcfi-mcp}
}
```

To cite the underlying CalcFi Open Data, see [`docs/CITATION.md`](docs/CITATION.md).

## Links

- Website: <https://calcfi.app>
- Methodology: <https://calcfi.app/methodology>
- Open data: <https://calcfi.app/data>
- Datasets DOI: [10.5281/zenodo.XXXXXXX](https://doi.org/10.5281/zenodo.XXXXXXX)
- Issues: <https://github.com/jeresalmisto/calcfi-mcp/issues>
- Security: see [SECURITY.md](SECURITY.md)

## License

MIT for the server code. Datasets are [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Methodologies are open-publication.