Installation

Get firma running in about 5 minutes. You'll need Node.js 18+, Claude Desktop, and a free Finnhub account.

Requirements

Node.js 18 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.

Setup Steps

Install globally

npm install -g firma-app

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

Set your Finnhub API key

firma config set finnhub-key YOUR_KEY

Find your key at finnhub.io/dashboard under API Keys.

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.

Start talking to Claude

Open Claude Desktop. firma tools should appear in the toolbar. Just start a conversation — tell Claude what you own:

"I hold 392 shares of TSLA, average cost $245.68. I also have 156 NVDA at avg $128.05. Log these and show me my portfolio."

Claude calls add_txn for each trade and thenshow_portfolio — no CLI needed for the first setup.

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.