Installation

Get firma running in about 5 minutes. You'll need Node.js 22+, Claude Desktop, and free accounts at Finnhub and FRED.

Requirements

Node.js 22 or later

Check with node --version. Install from nodejs.org or via nvm / brew install node.

Claude Desktop

Required for the MCP integration. Firma registers itself as an MCP server that Claude can call. Download from claude.ai/download.

Finnhub API key (free)

Used for price sync, earnings, insider transactions, financials, and news. Sign up at finnhub.io. The free tier is sufficient.

FRED API key (free)

Used for macro indicators (VIX, yield curve, USD index, etc.) and the historical FX rate cache that powers accurate non-USD display of past entries. Sign up at fred.stlouisfed.org. Approval is instant.

Setup Steps

Install globally

npm install -g firma-app

Installs two binaries: firma (CLI) and firma-mcp (MCP server).

Set your API keys

firma config set finnhub-key YOUR_KEYfirma config set fred-key YOUR_KEY

Finnhub keys are at finnhub.io/dashboard. FRED keys are at fred.stlouisfed.org. Both are free.

Connect Claude Desktop

firma mcp install

Writes the MCP server entry into Claude Desktop's config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Restart Claude Desktop to activate.

Tell Claude what you own

Open Claude Desktop. Firma tools should appear in the toolbar. Drop a CSV / brokerage export / screenshot in chat (or just describe what you hold) and ask Claude to set up firma:

"[trades.csv attached] Set up firma with these. Then sync prices and FX, and show me my portfolio."

Claude calls add_txn for each row, then sync_prices + sync_fx_rates, then show_portfolio. No CLI commands needed for onboarding. See Importing Data for more examples covering balances and cash flow.

Daily routine

After the initial setup, just ask Claude for the brief once a day:

"Sync everything and give me today's brief."

Claude runs sync_prices + sync_fx_rates (incremental, sub-second after the first run), then get_brief. The response includes holdings with weights, today's P&L, news, upcoming earnings, macro context, and pre-computed insights. See Daily Brief.

Local Data

All data is stored in ~/.firma/firma.db (SQLite) and ~/.firma/config.json. Nothing is sent to Firma servers. Back up ~/.firma/ to preserve your financial history.

The SQLite file is readable with any SQLite client. Your data is never locked into a proprietary format.

Support firma

If firma has been useful, give it a star on GitHub. It keeps the project moving.

★Star on GitHub↗