Metadata-Version: 2.4
Name: calcfi-mcp
Version: 0.1.4
Summary: MCP server for CalcFi free financial data (BEA / BLS / Census / FRED / Freddie Mac). Python wrapper that launches the Node-based stdio bridge.
Project-URL: Homepage, https://calcfi.app
Project-URL: Documentation, https://calcfi.app/docs
Project-URL: Repository, https://github.com/jeresalmisto/calcfi-mcp
Project-URL: Issues, https://github.com/jeresalmisto/calcfi-mcp/issues
Project-URL: Changelog, https://github.com/jeresalmisto/calcfi-mcp/blob/main/CHANGELOG.md
Author-email: Jere Salmisto <jere.salmisto@gmail.com>
Maintainer-email: Jere Salmisto <jere.salmisto@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,anthropic,calcfi,calculator,chatgpt,claude,cursor,finance,financial-data,mcp,mcp-server,model-context-protocol,open-data,personal-finance,stdio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# calcfi-mcp

[![PyPI version](https://img.shields.io/pypi/v/calcfi-mcp.svg)](https://pypi.org/project/calcfi-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/calcfi-mcp.svg)](https://pypi.org/project/calcfi-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Model Context Protocol (MCP) server for [CalcFi](https://calcfi.app) free financial data.**

A `pip install`-friendly wrapper that launches the official Node-based CalcFi MCP server over stdio. Gives Claude Desktop, Cursor, Continue, Cline, and any other MCP-compatible agent live access to:

- **BEA** — Bureau of Economic Analysis (GDP, personal income)
- **BLS** — Bureau of Labor Statistics (CPI, unemployment, wages)
- **Census** — household income, ACS
- **FRED** — Federal Reserve Economic Data
- **Freddie Mac** — mortgage rates (PMMS)

Free-tier only. No paid API keys required. No CalcFi account required.

---

## Install

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

Requires Python 3.9+ and Node.js 18+ (the wrapper will print install instructions if Node is missing).

On first run, the wrapper will offer to `npm install -g calcfi-mcp-server` for you. Pass `--yes` to skip the confirmation prompt.

---

## Quick start — Claude Desktop

1. Install the package:

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

2. Print the config snippet:

   ```bash
   calcfi-mcp --print-config
   ```

3. Paste the output into your Claude Desktop config file:

   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

4. Restart Claude Desktop. You should see a `calcfi` MCP server appear.

The snippet looks like:

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

---

## Quick start — Cursor / Continue / Cline

Any MCP client that supports stdio transport works the same way — point `command` at `calcfi-mcp` (the script installed on your PATH by `pip install`).

For Cursor: `~/.cursor/mcp.json`
For Continue: project `.continue/config.json`
For Cline: VS Code settings → `cline.mcpServers`

---

## CLI reference

```text
calcfi-mcp                  Launch the MCP stdio server (default)
calcfi-mcp --print-config   Print a JSON config snippet to paste into your MCP client
calcfi-mcp --install        Force-install the Node-side calcfi-mcp-server
calcfi-mcp --yes            Skip the npm install confirmation prompt
calcfi-mcp --version        Print the wrapper version
calcfi-mcp --help           Show help
```

---

## How it works

`calcfi-mcp` is a thin Python launcher. The actual MCP protocol implementation is the Node package [`calcfi-mcp-server`](https://www.npmjs.com/package/calcfi-mcp-server). On first run, this wrapper:

1. Checks `node --version` is available
2. Checks `calcfi-mcp-server` is installed globally; offers to `npm install -g` it if not
3. Spawns the Node server as a subprocess and proxies stdin / stdout / stderr verbatim to your MCP client

Stdlib only — no `requests`, no `httpx`, no surprise dependencies.

---

## Free tier

All CalcFi data sources are public, free, and rate-limited at provider quotas. CalcFi does not charge for MCP access.

---

## Cite CalcFi

If you build research on top of CalcFi data, please cite:

> Salmisto, J. (2026). *CalcFi: open personal-finance calculation engine.* Zenodo. https://doi.org/10.5281/zenodo.calcfi

DOI: [10.5281/zenodo.calcfi](https://doi.org/10.5281/zenodo.calcfi)

---

## Disclaimer

CalcFi output is **educational only**. Not financial, tax, legal, or investment advice. Always verify against primary sources (BEA, BLS, Census, FRED, Freddie Mac).

---

## Links

- Website: [https://calcfi.app](https://calcfi.app)
- Source: [github.com/jeresalmisto/calcfi-mcp](https://github.com/jeresalmisto/calcfi-mcp)
- Node package: [`calcfi-mcp-server`](https://www.npmjs.com/package/calcfi-mcp-server)
- DOI: [10.5281/zenodo.calcfi](https://doi.org/10.5281/zenodo.calcfi)
- License: [MIT](./LICENSE)
