firma
You earned well this year.
Do you know where it went?
Just ask Claude.
A local-first, AI-native CLI for overseas stock investors.
npm install -g firma-app
Track your portfolio, log trades, and analyze monthly cash flow — all from your terminal, all stored on your machine. Drop-in MCP integration means Claude reads, writes, and reasons about your finances directly. No vendor lock-in. No cloud sync. No financial data leaving your laptop.
In conversation with Claude
You: How is my portfolio doing?
Claude: Total market value is $147,509, up +$55,870 (+60.9%) from cost basis.
TSLA (392 shares) is driving most of the gain.
You: Spending feels high this month. How does it compare to last year?
Claude: March 2026 expenses were $3,050 — up 18% vs. March 2025.
Savings rate dropped from 41% to 34%.
You: I just bought 15 shares of AAPL at $211. Log it.
Claude: Done — AAPL 15 shares @ $211.00 recorded for 2026-04-25.
You: Give me a full overview of my finances with charts.
Claude: [renders live portfolio dashboard — holdings, net worth trend, asset mix, cash flow]
Why firma
- Local-first by design. Your transactions, balances, and cash flow live in
~/.firma/firma.db— a single SQLite file. Nothing syncs anywhere unless you ask it to. - MCP-native. Every CLI command has a matching MCP tool, so Claude can do everything you can — analyze, log, reconcile — through natural conversation.
- Built for overseas investors. Multi-currency support (USD, KRW, EUR, JPY, and more), fxratesapi auto-conversion, and Finnhub-powered prices for U.S. equities.
- Transactions as source of truth. No holdings table to drift out of sync — your portfolio is always derived from your trade log. Buy/sell/deposit/dividend/tax all supported.
- Developer-first UX.
--jsonoutput on every read command, scriptable, pipe-friendly. Three clean verb groups:add,show,report.
Get started
# 1. Install
npm install -g firma-app
# 2. Set your Finnhub key (free at finnhub.io)
firma config set finnhub-key YOUR_KEY
# 3. Connect Claude Desktop
firma mcp install
# Restart Claude Desktop — that's it.
# 4. Add your first trade and sync prices
firma add txn
firma sync
Already have data? Skip to firma show portfolio and let Claude take it from there.
Privacy
All financial data is stored in ~/.firma/firma.db — a local SQLite file only you can access. Nothing is sent to Firma servers.
- Prices → Finnhub, called directly with your own API key
- Exchange rates → open.er-api.com (no auth required)
- Claude reads data → local process-to-process via MCP protocol
Your numbers never leave your machine.
CLI reference
Three verb groups: add (input), show (read, --json everywhere), report (aggregated, --json everywhere).
| Command | What it does |
|---|---|
firma add txn | Record a transaction (buy / sell / deposit / dividend / tax) |
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 flow (month-end) |
firma show portfolio | Holdings overview with P&L (auto-syncs prices) |
firma show txns [ticker] | Transaction history with running avg cost |
firma show balance / flow [-p YYYY-MM] | Stored entries for a period |
firma show news / insider / financials / earnings <ticker> | Finnhub data |
firma report | Net worth trend + cash flow charts |
firma report balance / flow / settle | Targeted views |
firma report -c USD | Display in USD, EUR, JPY, CNY, or GBP |
firma edit txn [id] | Edit a transaction |
firma edit balance / flow [period] | Edit a monthly snapshot (existing values pre-filled) |
firma delete txn [id] | Delete a transaction |
firma delete balance / flow [period] | Delete all entries for a period (alias rm) |
firma sync | Fetch latest prices from Finnhub |
firma mcp install | Register MCP server in Claude Desktop |
firma config set finnhub-key KEY | Set Finnhub API key |
firma config set db-path PATH | Use a custom database location |
MCP tools
Available in Claude Desktop after firma mcp install. Same add_* / show_* / report_* shape as the CLI.
| Tool | What it does |
|---|---|
add_txn / edit_txn / delete_txn | Stock transaction CRUD |
add_balance / add_flow | Upsert (acts as edit when the composite key matches) |
delete_balance / delete_flow | Drop entries by period (or single composite key) |
show_portfolio | Holdings with P&L, avg cost, market value |
show_txns | Transaction history (filterable by ticker) |
show_balance / show_flow | Stored entries (filterable by period) |
show_prices | Cached price snapshots |
show_news / show_insider / show_financials / show_earnings | Finnhub passthroughs |
report_settle | Single-period summary with net_worth + net_flow |
sync_prices | Refresh prices from Finnhub |
Development
See CONTRIBUTING.md for architecture overview and extension points.
Requires Node.js 22+ and Yarn Berry.
corepack enable
yarn install
yarn dev:cli show portfolio # CLI dev mode
yarn typecheck # Full type check
Default DB is ~/.firma/firma.db. To use a separate file during development:
firma config set db-path ./dev.db
License
MIT © Evan Moon