firma

<p align="center"> <img src="https://raw.githubusercontent.com/evan-moon/firma/main/assets/og-image.png" alt="firma" width="560" /> </p>

<h1 align="center">firma</h1>

<p align="center"> <strong>You earned well this year.<br/>Do you know where it went?</strong> </p>

<p align="center"> Drop your trade history into Claude.<br/> Get back a full financial picture — portfolio, net worth, cash flow — stored in a local SQLite file. </p>

<p align="center"> <a href="https://www.npmjs.com/package/firma-app"><img src="https://img.shields.io/npm/v/firma-app.svg?style=flat&color=cb3837&logo=npm" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="License: MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat&logo=node.js&logoColor=white" alt="Node >= 22"></a> <a href="https://glama.ai/mcp/servers/evan-moon/firma"><img src="https://glama.ai/mcp/servers/evan-moon/firma/badges/score.svg" alt="firma MCP server"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-ready-7c3aed?style=flat" alt="MCP-ready"></a> </p>

<p align="center"> <code>npm install -g firma-app</code> </p>

<p align="center"> <img src="https://raw.githubusercontent.com/evan-moon/firma/main/assets/demo_short.gif" alt="Claude MCP visualizing finance data" width="700" /> </p>

---

You:    Here's my IBKR trade history [trades.csv]. Set up firma.
Claude: I see 47 transactions. Logging in chronological order... done.
        Syncing prices and FX history... your portfolio: $179K, +61% all-time. TSLA is 78%.

You:    My portfolio feels really volatile lately. Should I be worried?
Claude: TSLA is 74% of your equity — a 10% TSLA move is a 7% net worth move.
        Cash flow is solid at $6.4k/month saved. The volatility is market, not lifestyle.

You:    That July expense spike looks alarming.
Claude: That was $57k in TSLL — a leveraged bet, not spending.
        Strip it out: expenses flat at ~$7k/month, savings rate 47.8%.

You:    Give me a full overview with charts.
Claude: Net worth: $294k → $490k in 8 months, pulled back to $427k with TSLA's Q1 dip.
        [builds net worth trend, income vs expenses, portfolio allocation, unrealized P&L]

---

Why firma

• Talks to Claude natively. firma mcp install wires firma into Claude Desktop. Every command you can run in the terminal, Claude can call through MCP — log trades, sync prices, render charts, reason about your data.
• Local-first, no exceptions. Everything lives in ~/.firma/firma.db. No server, no sync, no account. Your financial data never leaves your machine.
• Built for US market investors. Multi-currency (USD, KRW, EUR, JPY, and more) with historical FX rates from FRED — so a 2018 balance shows the 2018 exchange rate, not today's.
• Transactions as source of truth. No holdings table to drift out of sync. Portfolio, cost basis, and P&L are always derived live from your trade log.
• Developer-friendly. --json on every read command. Three clean verb groups: add, show, report.

---

Get started

# 1. Install
npm install -g firma-app

# 2. Set API keys (both free)
firma config set finnhub-key YOUR_KEY   # finnhub.io — prices, news, earnings
firma config set fred-key YOUR_KEY      # fred.stlouisfed.org — macro & FX history

# 3. Connect Claude Desktop
firma mcp install
# Restart Claude Desktop — firma tools will appear in the toolbar.

4. Drop your data into Claude. Paste a CSV, brokerage export, or plain text — Claude logs everything and syncs prices automatically.

Prefer the terminal? Every MCP tool has a matching firma command — see CLI reference.

---

CLI reference

--json is available on every read command. Alias: firma rm = firma delete.

Portfolio

Command	What it does
firma show portfolio	Holdings with P&L, avg cost, market value
firma show txns [ticker]	Transaction history with running avg cost
firma show dividend	Estimated annual income + per-ticker yield
firma show concentration	HHI concentration by ticker, currency, sector, country
firma show snapshot [ticker]	Portfolio value history; --from/--to for date range
firma show benchmark	Portfolio return vs SPY/QQQ (or custom benchmarks via -b)
firma show risk	Volatility, drawdown, Sharpe, Sortino, beta — requires snapshots

Balance & Cash Flow

Command	What it does
firma add balance [-p YYYY-MM]	Monthly asset & liability snapshot
firma add flow [-p YYYY-MM]	Monthly income & expense entry
firma add monthly [-p YYYY-MM]	Balance + flow in one call (month-end)
firma show balance [-p YYYY-MM]	Stored balance entries for a period
firma show flow [-p YYYY-MM]	Stored cash flow entries for a period
firma report	Net worth trend + cash flow charts (combined)
firma report balance / flow / settle	Targeted views
firma report -c USD	Display in USD, EUR, JPY, CNY, or GBP

Transactions

Command	What it does
firma add txn	Record a transaction (buy / sell / deposit / dividend / tax)
firma edit txn [id]	Edit a transaction
firma delete txn [id]	Delete a transaction

Snapshots

Command	What it does
firma add snapshot	Sync prices and record today's portfolio snapshot
firma edit snapshot	Edit a snapshot entry (interactive picker)
firma delete snapshot [date]	Delete all entries for a date

Research (Finnhub)

Command	What it does
firma show news <ticker>	Recent company news
firma show insider <ticker>	Insider buy/sell transactions
firma show financials <ticker>	SEC-reported quarterly financials
firma show earnings [ticker]	Earnings calendar + EPS history

Macro (FRED)

Command	What it does
firma show macro	VIX, 10Y yield, yield curve, USD index, HY spread, inflation, fed funds, FX
firma show stress	Economic Stress Index (0–100) from 5 FRED series
firma show regime	Macro regime bias — Risk-on / Mixed / Risk-off
firma show fx [currency]	Inspect cached FX history with --from/--to/--limit

Daily Brief & Actions

Command	What it does
firma brief	Movers, news, upcoming earnings, macro context (cached per day; --refresh to regenerate)
firma sync	Fetch latest prices (Finnhub) + FX rate history (FRED)
firma sync fx	FX history only — incremental backfill from your earliest entry date
firma doctor	Check setup status — API keys, data, FX cache
firma mcp install	Register MCP server in Claude Desktop
firma config set finnhub-key KEY	Set Finnhub API key
firma config set fred-key KEY	Set FRED API key
firma config set currency CODE	Set home currency (KRW, USD, JPY, …)

---

Claude integration (MCP)

After firma mcp install, Claude has full read/write access to your data through conversation. Two tools are available only via MCP:

Tool	What it does
fetch_fred_series	Fetch any FRED time series by ID (800K+ series)
search_fred_series	Search the FRED catalog by keyword

get_brief is the richest single call for daily check-ins — holdings with weights, daily P&L, concentration, movers, news, earnings, macro context, stress/regime signals, all in one response. If today's snapshot is missing, get_brief records one automatically before assembling the brief, so daily history accrues even when you forget to run firma add snapshot.

Prompts — type / in Claude Desktop to access guided workflows:

Prompt	What it does
import-trades	Confirms column mapping before writing — reliable bulk import from any CSV or spreadsheet
month-end	Walks through balance + cash flow entry for the period, submits in one batch
morning	Calls get_brief and surfaces only what needs attention
analyst	Activates a financial-analyst persona — Claude leads with concentration risk, frames every number against net worth or runway, and combines portfolio + cash flow + macro into a single view

setup_status (called by Claude at the start of any conversation) also returns an analyst_context block — a lightweight version of the analyst persona that influences every reply without a manual prompt invocation.

Historical FX note: firma sync fx backfills daily KRW/JPY/EUR/CNY/GBP rates from FRED starting at your earliest transaction date. Subsequent runs are increment-only. This means a 2018 balance in KRW uses the 2018 rate — not today's.

---

Development

Requires Node.js 22+ and Yarn Berry.

corepack enable
yarn install

yarn dev:cli show portfolio    # CLI dev mode
yarn typecheck                 # Full type check

See CONTRIBUTING.md for architecture overview and extension points.

---

License

MIT © Evan Moon