firma
firma is a local-first, AI-native MCP server for managing overseas stock investments, personal finances, and portfolio analytics — all stored locally on your machine.
Portfolio Management: View holdings with average cost, P&L, and market value (
show_portfolio); view cached price snapshots (show_prices); sync latest prices from Finnhub (sync_prices).Transaction Tracking: Record buy/sell/deposit/dividend/tax entries (
add_txn), edit (edit_txn) or delete (delete_txn) by ID, and list history with optional ticker filter (show_txns).Balance Sheet Management: Add/update monthly asset and liability entries in KRW (
add_balance), view with optional period filter (show_balance), and delete entries (delete_balance).Cash Flow Management: Add/update monthly income and expense entries in KRW (
add_flow), view with optional period filter (show_flow), and delete entries (delete_flow).Financial Reporting: Generate a period summary with computed net worth and net flow (
report_settle).Market Research via Finnhub: Fetch company news (
show_news), insider transactions (show_insider), SEC-reported financials (show_financials), and earnings calendar (show_earnings).
All commands support --json output for scripting and piping.
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]Your brokerage app shows you a number. firma shows you the truth.
It talks to Claude. Natively. Every command lives behind MCP, log trades, sync prices, render charts, reason about your money. You type plain English; Claude does the rest.
Local-first, no exceptions. Everything sits in
~/.firma/firma.db. No server, no sync, no account. Your financial data never leaves your machine. Ever.Nine markets, one source of truth. US, KRX, KOSDAQ, JP, HK, LSE, XETRA, NSE, TW, plus crypto, commodities, and real estate. Stored in USD, shown in any currency, with historical FX from FRED: a 2018 balance gets the 2018 rate, not today's.
No holdings table to lie to you. Portfolio, cost basis, P&L, all derived live from your trade log. Nothing drifts out of sync, because there's nothing to drift.
A brief that actually has an opinion.
get_market_briefdoesn't dump data, it takes a stance. A weekly lean (aggressive or defensive), a ranked call per holding (BUY / ADD / HOLD / TRIM / SELL / AVOID with conviction and an English thesis), and a watchlist of what to look at next. Every holding is classified, run through a category playbook, and checked by a correlation guard that catches "more of what you already own" before it lands.A simulator nobody else ships.
project_net_worthruns multi-scenario Monte Carlo over your portfolio at any horizon, next month or 30 years, one tool.simulate_scenariodoes the deterministic day-to-week version ("PCE comes in hot Thursday, how much does that cost me?"). You supply the assumptions, Claude discloses them verbatim, firma does the math. No hidden "advisor view."Time-series features from day one. The first
firma syncbackfills 90 days of daily history. Correlation, Sharpe, max drawdown, volatility, CAGR, populated immediately, not 30 days from now.It tracks your decisions, not just your positions.
show_thesis_trackreads your own trade reasons back to you against the outcome.show_anti_portfoliofollows what you sold, the data brokerages hide because it exposes bad exits.
Related MCP server: FinLynq
Get started
# 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, then restart it
firma mcp installRather not touch a terminal? Grab the macOS or Windows installer, Node.js is bundled, Claude is wired up for you.
Then drop your data into Claude, a CSV, a brokerage export, plain text. It logs everything and syncs prices automatically.
If firma helps you see where your money went, ⭐ star the repo, it's the cheapest way to help others find it.
How it's split: MCP thinks, the CLI keeps you safe
firma is MCP-first. Analysis, briefs, recommendations, news, valuation, projections, all of it happens in conversation with Claude. The CLI exists for the three things a chat can't safely own: setup, manual data entry, and repair.
# Setup
firma config set <key> # finnhub-key / fred-key / currency
firma mcp install # register with Claude Desktop
firma doctor # check keys, data state, FX cache, coverage
# Manual entry
firma add txn # buy / sell / deposit / dividend / tax, any of 9 markets
firma add monthly # month-end balance + cash flow in one flow
firma add snapshot # sync prices, snapshot today's portfolio
# Repair (when Claude or you got it wrong)
firma edit txn / balance / flow / snapshot
firma delete txn / ... # alias: firma rm
# Verify (read-only, just confirm what landed in the DB)
firma show portfolio / txns / balance / flow / snapshot / profile / fx
# Sync
firma sync # prices (Finnhub) + FX history (FRED) + correlation cache
firma sync fx # FX history onlyEverything analytical (get_market_brief, every show_*, report, project_net_worth, simulate_scenario) lives in Claude. Two tool families that never mix: diagnostic (what's true right now, no fortune-telling) and thought experiment (what-ifs, assumptions always disclosed).
Architecture
A Yarn Berry monorepo with a strict port-and-adapter layout. The application layer never imports an external API directly, it talks to domain interfaces, and adapters implement them.
packages/
domain/ ports + types, zero external-API knowledge
external-api/ raw clients (finnhub, fred, worldbank, gdacs, yahoo, …), zero domain knowledge
adapter/ the only layer that imports both sides
use-case/ business logic (portfolio, brief, advisor, projection, scenario)
shared/ db + utils
apps/
cli/ mcp/ docs/The rule: external-API packages know nothing about firma's domain; domain packages know nothing about any external API. @firma/adapters is the single bridge. Adding a data source touches no command and no business logic, a new raw client, one adapter, one registration line.
See CONTRIBUTING.md for the full walkthrough and the recipe for adding a provider.
Development
Requires Node.js 22+ and Yarn Berry.
corepack enable
yarn install
yarn dev:cli show portfolio # CLI dev mode
yarn typecheck
yarn testThe ecosystem
firma is one of three local-first tools that share one principle, your data stays on your machine, and the AI comes to it. They interoperate through any MCP client, and none depends on the others.
flowchart TB
U([You])
subgraph I["Interfaces, talk to your tools"]
direction LR
CD[Claude Desktop]
CC[Claude Code]
H["Herald · voice"]
end
subgraph T["Local-first tools, each owns its data, on your machine"]
direction LR
F["firma · money<br/>~/.firma"]
M["memex · memory<br/>~/.memex"]
S["skope · news<br/>~/.skope"]
end
U --> I
I -- MCP --> F & M & S
F <-. never call each other .-> M
M <-.-> Sfirma · money, portfolio, net worth, cash flow
memex · memory, notes and the context behind them, across sessions
skope · news, a personalized lens on the world
You reach them through Claude Desktop, Claude Code, Cursor, or Herald, a voice interface. The tools compose through the model, never by calling each other.
License
MIT © Evan Moon
Available Tools
37 toolsadd_balanceA
Upsert one or more balance sheet entries (also edits — same composite key overwrites). entries is an array: pass one entry to record a single balance item, many to import a net-worth spreadsheet (rows = months, columns = categories) in one call. Prefer add_monthly for full month-end settlement. sub_type: cash|investment|other (assets) or short_term|long_term (liabilities). VALID BALANCE CATEGORIES — assets: cash, savings, housing_sub, usd_cash, cash_other, domestic_stock, overseas_stock, real_estate, pension, vehicle, deposit, asset_other. Liabilities: credit_card, short_term_other, loan, long_term_other. Use ONLY these category strings — do NOT invent your own. For non-USD users: pass currency as the native currency (e.g. "KRW") and amount in that currency — converted to USD via historical FX at date. Use category="usd_cash" (currency="USD") for USD-denominated assets held alongside home-currency ones.
A single-entry call returns the upserted entry; a multi-entry call returns counts grouped by period.
Inputs: entries (required).
add_flowA
Upsert one or more cash flow entries (also edits — same composite key overwrites). entries is an array: pass one entry to record a single flow item, many to import an income/expense spreadsheet (rows = months, columns = categories) in one call. Prefer add_monthly for full month-end settlement. VALID FLOW CATEGORIES — income (sub_type=employment): salary, business. Income (sub_type=investment): dividends, interest. Income (sub_type=other): income_other. Expense (sub_type=consumption): personal. Expense (sub_type=fixed): insurance, phone, utilities. Expense (sub_type=housing): rent, maintenance. Expense (sub_type=debt): loan_repayment. Expense (sub_type=other): expense_other. Use ONLY these category strings — do NOT invent your own.
A single-entry call returns the upserted entry; a multi-entry call returns counts grouped by period.
Inputs: entries (required).
add_monthlyA
Batch upsert balance and flow entries for a single period in one call. Primary tool for month-end settlement / 월말 결산. When the user says "결산", "월말 결산", "month-end closing", or "record this month" — do NOT just display data. Instead: (1) ask for each balance category and each cash flow category; (2) confirm the numbers; (3) call this tool once with the full arrays. VALID BALANCE CATEGORIES — assets: cash, savings, housing_sub, usd_cash, cash_other, domestic_stock, overseas_stock, real_estate, pension, vehicle, deposit, asset_other. Liabilities: credit_card, short_term_other, loan, long_term_other. VALID FLOW CATEGORIES — income: salary (employment), business (employment), dividends (investment), interest (investment), income_other (other). Expense: personal (consumption), insurance (fixed), phone (fixed), utilities (fixed), rent (housing), maintenance (housing), loan_repayment (debt), expense_other (other). Use ONLY these category strings and their matching sub_type — do NOT invent your own. After recording, call report with target "settle" to show the confirmed summary.
Inputs: period (required), date (required), balance, flow.
add_priceA
Set the current price of ONE non-stock asset (crypto / commodity / real_estate / other). These assets have no market data provider, so their market value is entered manually — unlike stocks, which are auto-priced by sync (scope='prices'). Resolve name against the user's non-stock holdings (case-insensitive). value is in currency (default USD) and is converted to USD at today's date before storing. Calling it for a stock returns an error (stocks are auto-priced — use sync with scope='prices'); an unknown name returns a clear not-found error.
Inputs: name (required), value (required), currency.
add_snapshotA
Sync latest prices from Finnhub then record a portfolio snapshot for today. Required before snapshot data is useful.
Inputs: no named parameters.
add_txnA
Insert one or more transactions in a single call. transactions is an array — pass one entry for a single trade, many for a CSV / brokerage export / paste import. Rows are sorted by date ascending before insertion (average cost depends on insertion order). For bulk imports: first show the user your detected column mapping and total row count, wait for their confirmation, then call this once with all rows. Types: buy/sell move shares; deposit adds shares (set price=0 for grants/transfers, or actual cost basis); dividend/tax record cash events (price = total amount, shares = 1).
Reason capture (critical for thesis tracking): For NEW buy/sell trades — not historical bulk imports — the reason field is the single highest-leverage input you can capture for the user's long-term self-feedback loop (powers show_thesis_track later). When the user logs a NEW single buy/sell without supplying a reason, ALWAYS ask before calling: "What's your reason for this trade? Even one short sentence — 'earnings beat thesis', 'rebalancing toward defensive', 'avg-down on dip' — is enough." Then include their answer in reason. Skip the ask only when (a) the user is explicitly migrating historical data, or (b) the trade type is deposit/dividend/tax (no investment decision).
Each row carries its own asset_type (default 'stock'), which splits two flows:
stock:
priceis in the market's native currency (US→USD, KRX/KOSDAQ→KRW, JP→JPY, HK→HKD, LSE→GBP, XETRA→EUR, NSE→INR, TW→TWD) —marketdetermines it, thecurrencyparam is ignored. Non-US holdings must setmarketto the listing exchange;tickerstays the bare local code (e.g. market: "KRX", ticker: "005930").crypto / commodity / real_estate / other: there is no market or price provider — these are priced manually (not auto-synced).
marketis ignored and stored null,tickeris a free-form name (e.g. "Bitcoin", "Seoul apartment"), andpriceis in thecurrencyparam (default USD).
In both cases price is converted to USD at the transaction date before storing — every stored price is USD.
A single-entry call returns the inserted transaction; a multi-entry call returns a per-ticker / per-type summary.
Inputs: transactions (required).
delete_balanceA
Delete balance entries for a period. If category is provided, only that single entry is removed; otherwise all entries for the period are deleted.
Inputs: period (required), type, sub_type, category.
delete_flowB
Delete flow entries for a period. If category is provided, only that single entry is removed; otherwise all entries for the period are deleted.
Inputs: period (required), type, sub_type, category.
delete_snapshotA
Delete all portfolio snapshot rows for a given date (YYYY-MM-DD). Use only when the user explicitly asks to remove a bad snapshot — destructive.
Inputs: date (required).
delete_txnA
Delete a single transaction by its id. The user must confirm — never call this without explicit instruction (e.g. "delete transaction #42"). Removing a transaction recalculates all subsequent positions/avg cost since holdings are derived from the log.
Inputs: id (required).
edit_snapshotA
Update shares, avg_price, or current_price for a holding in a snapshot. Identified by date + the asset (asset_type + market + ticker). Works for non-stock assets too — pass their asset_type; market is ignored for non-stock.
Inputs: date (required), ticker (required), asset_type, market, +3 more.
edit_txnA
Update fields of an existing transaction by id. Only provided fields are changed.
When price is supplied it is converted to USD at the transaction date before storing. The native currency it is interpreted in depends on the (effective) asset type: for a stock it is the market's native currency (the new market if passed, else the existing one); for a non-stock asset it is the currency param (default USD).
Changing asset_type mirrors add_txn's fork: switching TO a non-stock type (crypto/commodity/real_estate/other) clears market to null (any market arg is ignored); switching TO 'stock' uses the supplied market (or keeps the existing one, defaulting to US).
Inputs: id (required), ticker, asset_type, date, +6 more.
get_market_briefA
Diagnostic: ALL-IN-ONE composite read of current portfolio state. Call this FIRST for any portfolio, market, regime, or check-in question - it returns a comprehensive snapshot in a single response, so you almost never need multiple tool calls just to answer 'how am I doing today'. Returns deterministic, rule-derived facts only — no forward-looking probability distributions, no caller-supplied assumptions. For probabilistic projections (FIRE timelines, short-horizon outlooks under explicit assumptions), use project_net_worth. All monetary values come back in display_currency (default USD). Bundles: meta (single gate capsule with base_date, fx state, fx_caveat, is_nyse_open, display_currency, presentational_constraints), portfolio + holdings (with per-stock fundamentals), concentration (HHI + effective_n + 90d correlations), diversification_insight + diversification_gaps, movers, news (with rule-derived attribution), earnings_upcoming + ipo_calendar + dividend_calendar + economic_calendar, macro + signals (regime, stress, next_week_scenarios), global_macro + disasters, commodities, snapshot_comparison + week_performance, risk_summary, goal_tracking (measured CAGR vs needed CAGR — no projected_net_worth), stance, recommendations (with size_hint.phases / event_window / proceeds / funded_by_rec_ids / is_ceiling_breached), rebalance_chain, watchlist. show_* tools are drill-downs, not peers - call them only when the user asks for a single dimension in more detail than the brief carries. Cached per day on disk.
Inputs: refresh, display_currency.
project_net_worthA
Thought experiment: forward-looking Monte Carlo projection of net worth under caller-supplied assumptions, multi-scenario. Runs monthly GBM under one or more (return, vol) pairs in parallel, adds a fixed monthly contribution, applies one-time life events, and returns P10 / P25 / P50 / P75 / P90 trajectories per scenario. horizon_months accepts any length from 1 (next month) to 720 (60 years) — same tool answers short-horizon outlooks and long-horizon FIRE planning. target_value is optional: when supplied, the response includes probability of reaching it and median months to reach; when omitted, just the distribution at the horizon. All monetary inputs/outputs are in the requested currency (default USD). YOU MUST set scenarios[].expected_annual_return and scenarios[].annual_volatility explicitly and disclose them verbatim to the user — firma does NOT bake in defaults. For reference, brief.risk_summary carries the user's realized 90d annualized_return_pct and annualized_vol_pct — those make a natural 'historical' scenario you can contrast with bear/bull overlays. All scenarios share the same seeded shock sequence so cross-scenario differences reflect (return, vol) — not random noise. For current portfolio state, use get_market_brief — that is the diagnostic tool; this is the thought-experiment tool.
Inputs: initial_value (required), monthly_contribution (required), horizon_months (required), scenarios (required), +7 more.
reportA
Aggregated wealth reports. target selects the view: balance — monthly net worth trend; flow — monthly income, expenses, net flow, savings rate; settle — single-period balance + cash flow summary with computed totals (defaults to current month, use period to pick another); combined (default) — both balance and flow trends in one call. Primary entry point for wealth-trajectory questions ("are my assets growing?", "is my net worth trending up?", "am I getting wealthier?") — portfolio value alone is insufficient because it ignores cash savings, debt paydown, and savings rate. Pair with show_snapshot when the user wants the market-driven slice of the trajectory.
Inputs: target, period, currency, limit.
set_profileA
Update the user's profile. Partial updates — only provided fields are changed. All fields are optional; capture only what the user volunteers, never invent values. Birth year and retirement target year are 4-digit years; target_net_worth is in the supplied currency (default USD) and stored internally as USD via the latest FX rate; risk tolerance is one of conservative/moderate/aggressive; notes is free-form for preferences/constraints.
Inputs: birth_year, retirement_target_year, target_net_worth, currency, +2 more.
setup_statusA
One-shot setup diagnostic. Call this at the start of every conversation, and any time the user asks for analysis but you're unsure what data is available. Returns: API key state, data counts (transactions / balance / flow / prices / snapshots / FX), profile, next_steps for onboarding, capabilities (which kinds of analysis are currently possible), and analyst_context (the persona, principles, data_gating rules, and reasoning frameworks). Treat capabilities as a hard gate — if a required capability is false, follow the matching data_gating rule instead of fabricating an answer.
Inputs: no named parameters.
show_anti_portfolioA
Track the post-exit performance of positions the user has fully sold — the data brokerage apps deliberately don't show (because it would highlight bad sells). For each ticker the user once held but no longer does, returns the last sell date, last sell price, current price, days since exit, post-sell price change %, and a label: missed_rebound (+20% or more since sell — sell was likely premature), good_call (-20% or more — sell saved losses), neutral_exit, or too_recent (<14 days, signal noise). Use when the user is contemplating a sell, reviewing past decisions, or asking 'have my sells worked out?'. Pair with show_thesis_track to connect the original buy thesis to the sell outcome. The summary counts make the user's overall sell discipline visible at a glance.
Inputs: limit, display_currency.
show_balanceA
Stored balance sheet entries (assets + liabilities) by period. Each entry has type (asset|liability), sub_type (cash|investment|other|short_term|long_term), category, amount in display_currency (default USD), and the entry date. Without period, returns ALL periods — use this for trends; with period (YYYY-MM), returns one month's snapshot.
Inputs: period, display_currency.
show_benchmarkA
Compare portfolio return against benchmark indices (default: SPY and QQQ). Uses daily snapshot history when available for accurate time-series comparison; falls back to cost-basis vs current value when no snapshots exist.
Inputs: from, to, benchmarks.
show_concentrationA
Portfolio concentration measured by Herfindahl-Hirschman Index (HHI) across ticker, currency, sector, and country dimensions. HHI ranges 0–10000; >2500 is high, >5000 very high. Returns top contributors per dimension, plus the pairwise 90-day correlation matrix and an effective-N (correlation-adjusted holdings count): two holdings at 0.9 correlation count as roughly one for diversification. effective_n / correlation_matrix_90d are null/empty until firma sync populates the correlation cache.
Inputs: no named parameters.
show_dividendA
Estimated annual dividend income for all holdings. Returns per-ticker yield, annual DPS, and estimated income in display_currency (default USD). Only includes tickers with dividend data.
Inputs: display_currency.
show_earningsA
Fetch earnings calendar. Without a ticker, returns upcoming earnings for all held tickers. With a ticker, returns history + upcoming.
Inputs: ticker, weeks, history.
show_financialsB
Fetch SEC-reported financials for a ticker. Returns key income statement, cash flow, and balance sheet metrics extracted from XBRL filings.
Inputs: ticker (required), freq, limit.
show_flowA
Stored monthly cash flow entries (income + expenses) by period. Each entry has type (income|expense), sub_type, category, amount in display_currency (default USD), date. Without period returns all periods; with period (YYYY-MM) returns one month. For trend analysis use report with target "flow" which aggregates and adds savings rate.
Inputs: period, display_currency.
show_fxA
Inspect the local FX rate cache (foreign per 1 USD). Without currency, returns per-currency coverage (count + first/last date). With currency + date, returns the point-in-time rate, falling back to the most recent within lookback_days. With currency + from/to, returns the cached series for that range. With currency alone, returns the limit most-recent rows. USD has no rows (it's the base, always 1.0).
Inputs: currency, date, from, to, +2 more.
show_macroA
Curated macro snapshot in one view: 8 indicators (VIX, 10Y Treasury, yield curve, USD index, HY credit spread, breakeven inflation, Fed funds, plus FX vs the requested display currency, each with current value, 30d/90d delta, and 5y average), plus an Economic Stress Index (0–100 from 5 FRED series with per-component breakdown), and a macro regime bias (Risk-on / Mixed / Risk-off from 5 binary signals). The display_currency arg drives the FX series selection (USD = no FX line).
Inputs: display_currency.
show_newsA
Recent company news from Finnhub for a single ticker — headline, summary, source, published timestamp, URL. Default lookback is 7 days, capped to limit items (default 10). For news across all holdings in one call, prefer get_market_brief which aggregates the last 24h.
Inputs: ticker (required), days, limit.
show_portfolioA
Current holdings derived from the user's transaction log: ticker, shares, avg cost, current price, market value, P&L (absolute and %), plus an optional risk summary (Sharpe, volatility, drawdown) from snapshot history and FX return decomposition when a non-USD display currency is requested. All monetary values are returned in display_currency (default USD). Each holding carries asset_type (stock for listed equities; crypto/commodity/real_estate/other for manually-valued assets) and syncedAt — the price as-of date. For non-stock holdings syncedAt reflects the last add_price entry; a null syncedAt (or currentPrice) means the asset has never been priced. This is a drill-down tool: for any check-in or portfolio question, call get_market_brief first — it already includes this data plus weights, news, earnings, and macro context. Use show_portfolio only when the holdings table itself is the sole thing asked for, or to inspect FX decomposition.
Inputs: display_currency.
show_profileA
Read the user's stored profile (birth year, retirement target year, target net worth, risk tolerance, free-form notes). Target net worth is returned in display_currency (default USD). Returns null if no profile is set. Use this to anchor analysis to the user's actual goals rather than generic advice.
Inputs: display_currency.
show_riskA
Portfolio risk metrics derived from snapshot history: annualized volatility, max drawdown, Sharpe ratio, Sortino ratio, win rate, and beta vs benchmark. Requires at least 10 daily snapshots — if the user has fewer, suggest running firma add snapshot regularly.
Inputs: from, to, benchmark, risk_free_rate.
show_snapshotA
Query portfolio snapshot history. Without ticker, returns daily total market value in display_currency (default USD). With ticker, returns per-holding time series with prices in display_currency. IMPORTANT: For any projection, goal-timeline, or "when will I reach X" question, this tool alone is insufficient — it only provides historical trajectory. You must also call get_market_brief (for current macro regime, stress score, and signals) and use risk_summary.annualized_vol + signals.regime to build bear/base/bull scenarios rather than extrapolating linearly from past returns. Linear extrapolation from snapshot history is a category error for forward-looking questions.
Inputs: ticker, from, to, display_currency.
show_thesis_trackA
Review past trades that have a recorded reason (the thesis) and check whether each thesis played out. Returns each thesis trade with the buy price, current price, days held, price change %, whether the position is still held, and an outcome label (validated_holding / underwater_holding / cut_loss / etc — these are descriptive labels, not judgments). Use this when the user asks 'did my last trade work', 'what's the track record of my AAPL theses', 'review my decisions', or when reasoning about a new buy in the same name as past trades. Coverage_pct tells you what fraction of trades have a recorded reason — if low, encourage the user to add reason when logging future trades.
Inputs: ticker, limit, display_currency.
show_txnsA
Full transaction log (buys, sells, deposits, dividends, taxes) ordered by date ascending. Pass ticker to filter to one symbol — useful for "show me all my AAPL trades" or computing a per-position story. Works for non-stock asset names too (e.g. "Bitcoin"); the match is case-insensitive. Each row has the original currency it was entered in; price is returned in display_currency (default USD).
Inputs: ticker, display_currency.
show_valuationA
Valuation deep-dive for a single ticker: PEG ratio, Price/Sales, and FCF yield — computed from 8 quarters of SEC filings. Use when the user asks 'is X overvalued / cheap?', 'what's the PEG?', 'how does the valuation look?'. Requires Finnhub key. Market cap and PE come from the price cache; revenue, EPS, operating cash flow, and capex come from XBRL filings.
Inputs: ticker (required).
simulate_scenarioA
Call this for any short-horizon outlook question (1 day to 1 week). Trigger phrases: "내일", "tomorrow", "이번 주", "next week", "화요일", "수요일", "this Thursday", "how might X day look", "what if [macro event] happens", "FOMC 영향", "earnings 영향", "포트 어떻게 될까", "내 포트는 어떨까". DO NOT answer these from the brief alone — the brief is diagnostic only. This tool turns the brief's measured data into a quant answer. Thought experiment: deterministic conditional analysis. Given hypothetical market shocks, returns per-holding and portfolio P&L impact based on beta. Unlike project_net_worth (stochastic forward distribution over months/years), this is a point estimate per scenario for the immediate future — "if S&P moves −2% and your TSLA beta is 1.6, your TSLA P&L is impact_usd". Workflow: (1) call get_market_brief, (2) read holdings[].fundamentals.beta_5y into beta_overrides, (3) read risk_summary.daily_vol_pct into daily_vol_pct, (4) construct 2-3 scenarios (e.g. bear / base / bull at equity_pct -0.02 / 0 / +0.02; or hawkish / dovish for a Fed event). Caller MUST supply the shocks (the assumption) and disclose them in the answer. Without beta_overrides each ticker defaults to 1.0; without daily_vol_pct the one-sigma range is null. Use for next-day outlook ("if FOMC is hawkish?"), idiosyncratic event sizing ("my biggest position reports tomorrow, what's the dollar range?"), specific-day outlook ("화요일 시장 어떨까"), and rebalance impact ("if I trim TSLA and rotate to JNJ?"). For long-horizon projection (months/years, FIRE planning) use project_net_worth instead.
Inputs: scenarios (required), display_currency, beta_overrides, daily_vol_pct.
syncA
Refresh local caches. scope='prices' fetches latest stock prices (US via Finnhub, non-US via Yahoo, all stored in USD; requires finnhub_api_key). scope='fx' backfills the historical FX rate cache from FRED (KRW/JPY/EUR/CNY/GBP/HKD/INR/TWD per USD, increment-only; requires fred_api_key). scope='all' (default) runs prices then fx, mirroring firma sync.
Inputs: scope.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Tools are grouped by domain (transactions, balance, flow, portfolio, market analysis) with clear descriptions. Some overlap exists between get_market_brief and show_portfolio, but descriptions clarify the primary vs drill-down roles. Overall, distinct purposes are well-maintained.
Almost all tools follow a consistent verb_noun pattern (add_*, delete_*, edit_*, show_*, etc.). Exceptions like 'report' and 'sync' are still clear and do not break the pattern. Excellent consistency.
At 37 tools, the server is heavy but covers a broad domain (personal finance, investments, market data). While many tools are justified, the count is on the high side for typical MCP servers, potentially overwhelming for users.
The tool surface is remarkably complete: CRUD for transactions, balance, flow, snapshots; analytical reports, market data, projections, risk metrics, thesis tracking, and profile management. Nearly every common financial operation is supported without obvious gaps.
Maintenance
Related MCP Connectors
Your investing research inside Claude: watchlists, financial ratios, reverse-DCF valuations, investment theses, notes, portfolio, earnings calendar and news for the companies you follow. 70 read and write tools; ask what's on your morning desk, rank a watchlist by ROE, log a trade or save a thesis. OAuth sign-in. Free to start.
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
SEC filings for Claude, ChatGPT, Cursor — 23 tools + 5 recipes. Financials, insider, 13F, funds.
Connect Claude, ChatGPT, Codex, Claude Code or another MCP client to your real multi-broker investment portfolio. Fortunest tracks stocks, ETFs and crypto across brokers and exchanges; its MCP server lets your agent read holdings, returns, allocation, risk, trades and tax lots, calculated by Fortunest rather than guessed by the model. Reads run on their own; every change waits for your approval in the Fortunest app, and no tool places an order or moves money. Sign-in is OAuth 2.1 and needs Fortunest Pro (14-day trial, no card). A free demo that needs no account is listed as Fortunest demo.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenancemcprice ⚡ MCP Server for real-time stock & crypto prices in Claude Desktop / Cursor. Stocks → Yahoo Finance (no API key needed) Crypto → Binance Public API (no API key needed) Companion to: revolut-pulse (insider trades)-
- AlicenseCqualityAmaintenanceopen-source personal finance app with a first-party MCP server. 91 HTTP tools (OAuth 2.1 + DCR) and 87 stdio tools cover transactions, budgets, accounts, portfolio analytics, FX conversion, loans, subscriptions, goals, importers, and rules. Users self-host with Docker + PostgreSQL or use the managed cloud8935AGPL 3.0
- AlicenseAqualityBmaintenanceSelf-hosted financial data terminal for AI agents. Scrapes and serves SEC filings (full-text search), 13F institutional holdings, insider and congressional trades, FINRA short data, FRED economic indicators, CFTC futures positioning, VIX/put-call ratios, and daily stock prices over MCP.65247AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceLocal-first markdown vault with a built-in MCP server (streamable HTTP). 16 tools and 2 resources for Claude Code / Desktop / Cursor: read/write/search plus context_for_query, find_orphans, weekly_digest, compare_notes, semantic_outline. Per-folder agent permissions, LanceDB vectors, local Xenova ONNX embedder swappable to Ollama. Single Bun binary. AGPL.40AGPL 3.0