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]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.
Daily brief with world context. get_brief bundles holdings, macro signals, commodity prices, dividend calendar, global macro (World Bank), and active disaster alerts (GDACS) in one call — no extra API keys needed for the global data.
Developer-friendly. --json on every read command. Three clean verb groups: add, show, report.
Related MCP server: FinLynq
# 1. Install
npm install -g @evan-moon/firma
# 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
firmacommand — see CLI reference.
If firma helps you track your money, please ⭐ star the repo — it's the cheapest way to help others find it.
--json is available on every read command. Alias: firma rm = firma delete.
Command | What it does |
| Holdings with P&L, avg cost, market value |
| Transaction history with running avg cost |
| Estimated annual income + per-ticker yield |
| HHI concentration by ticker, currency, sector, country |
| Portfolio value history; |
| Portfolio return vs SPY/QQQ (or custom benchmarks via |
| Volatility, drawdown, Sharpe, Sortino, beta — requires snapshots |
| Set up your goals (birth year, retirement target, target net worth, risk tolerance, notes) — every field optional |
| Show the stored profile |
Command | What it does |
| Monthly asset & liability snapshot |
| Monthly income & expense entry |
| Balance + flow in one call (month-end) |
| Stored balance entries for a period |
| Stored cash flow entries for a period |
| Net worth trend + cash flow charts (combined) |
| Targeted views |
| Display in USD, EUR, JPY, CNY, or GBP |
Command | What it does |
| Record a transaction (buy / sell / deposit / dividend / tax) |
| Edit a transaction |
| Delete a transaction |
Command | What it does |
| Sync prices and record today's portfolio snapshot |
| Edit a snapshot entry (interactive picker) |
| Delete all entries for a date |
Command | What it does |
| Recent company news |
| Insider buy/sell transactions |
| SEC-reported quarterly financials (income, cash flow, balance sheet) |
| PEG ratio, P/S, FCF yield — computed from 8 quarters of SEC filings |
| Earnings calendar + EPS history |
Command | What it does |
| VIX, 10Y yield, yield curve, USD index, HY spread, inflation, fed funds, FX |
| Economic Stress Index (0–100) from 5 FRED series |
| Macro regime bias — Risk-on / Mixed / Risk-off |
| Inspect cached FX history with |
Command | What it does |
| World Bank macro (GDP, inflation, unemployment) + GDACS active disaster alerts in one view |
Command | What it does |
| Daily intelligence brief: movers, news, earnings, macro, commodities, dividend calendar, world macro, disaster alerts (cached per day; |
| Fetch latest prices (Finnhub) + FX rate history (FRED) |
| FX history only — incremental backfill from your earliest entry date |
| Check setup status — API keys, data, FX cache |
| Register MCP server in Claude Desktop |
| Set Finnhub API key |
| Set FRED API key |
| Set home currency (KRW, USD, JPY, …) |
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 any FRED time series by ID (800K+ series) |
| Search the FRED catalog by keyword |
get_brief is the primary entry point for any daily check-in or market question. In a single call it returns:
Portfolio — holdings with weights, daily P&L, total cost vs market value
Concentration — HHI by ticker, sector, currency, country
Movers — top winners and losers for the day
News — recent headlines per holding
Earnings — upcoming earnings dates with EPS estimates
Economic calendar — high/medium-impact events for the week
Macro — FRED snapshot (VIX, 10Y yield, credit spread, fed funds, FX impact in home currency)
Stress & Regime — Economic Stress Index + Risk-on / Mixed / Risk-off bias
Commodities — WTI oil, gold, copper (via FRED — no extra key)
Dividend calendar — upcoming ex-dates and estimated income for held positions
World macro — GDP growth, inflation, unemployment across major economies (World Bank — no extra key)
Disaster alerts — active GDACS Orange/Red events (no extra key)
Insights — cross-referenced observations that tie portfolio exposure to macro context
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.
show_valuation and show_world_intel are available for deeper drill-downs after reading the brief.
Prompts — type / in Claude Desktop to access guided workflows:
Prompt | What it does |
| Confirms column mapping then bulk-inserts every row in a single |
| Same flow for a net-worth spreadsheet (rows = months, columns = balance categories) → bulk |
| Same flow for an income/expense spreadsheet → bulk |
| Walks through balance + cash flow entry for the period, submits in one batch |
| Calls |
| 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 |
| Captures your goals (birth year, retirement target, target net worth, risk tolerance, notes) so all future analysis is anchored to them — every field optional |
| Five plausible ways a position could go wrong over 12 months — concrete failure modes tied to actual data, with portfolio impact in dollars |
| Compares current allocation against your stated target, flags drift, suggests specific trades while accounting for tax cost and wash-sale risk |
| Scans unrealized losses, checks 30-day wash-sale rule, suggests similar-but-not-identical replacements, estimates tax savings by bracket |
| Models a market shock or macro shift on your actual portfolio with explicit beta assumptions you can override |
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.
Requires Node.js 22+ and Yarn Berry.
corepack enable
yarn install
yarn dev:cli show portfolio # CLI dev mode
yarn typecheck # Full type checkSee CONTRIBUTING.md for architecture overview and extension points.
Firma is the financial intelligence layer of the Herald ambient voice assistant stack. When connected, Herald can:
report your portfolio performance and net worth by voice
answer "how much did I spend on fees this quarter?" without opening a spreadsheet
surface market context mid-conversation alongside your own position data
Herald + Firma + Memex — ambient voice, financial intelligence, and persistent memory in one personal AI stack.
MIT © Evan Moon
Global stock research, ML forecasts, valuation signals, screeners & portfolio tracking in Claude
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/evan-moon/firma'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
