Skillget

firma

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This is a local-first command-line tool and MCP server that helps overseas investors track their portfolio and net worth. You provide your trade history, and the application analyzes your finances and stores the data in a local SQLite file.

Security Assessment
Overall Risk: Low. The tool handles highly sensitive data—your personal financial and trade history—but the architecture is fundamentally sound. The code stores all data locally in a SQLite database and explicitly states that no information leaves your machine. A light code audit of 12 files found no hardcoded secrets, no dangerous permissions, and no malicious patterns. However, the application must make outbound network requests to fetch historical exchange rates and current stock prices. While the scan found no obvious dangers, always be aware that importing your brokerage CSV files into any third-party tool exposes your financial footprint.

Quality Assessment
The project is licensed under the standard MIT license and the repository is very active, with the most recent code pushed today. The main drawback is extremely low community visibility. With only 5 stars on GitHub, the project has not been widely peer-reviewed or battle-tested by a large user base. As a result, community trust cannot be deeply established yet, so you are relying primarily on the creator's code quality.

Verdict
Safe to use, but keep in mind that the tool handles sensitive financial data and has not been widely vetted by the broader developer community.
SUMMARY

Local-first CLI portfolio tracker for overseas investors, with built-in MCP server for Claude

README.md

firma

firma

You earned well this year.
Do you know where it went?

Drop your trade history into Claude.
Get back a full financial picture — portfolio, net worth, cash flow — stored in a local SQLite file.

npm version License: MIT Node >= 22 firma MCP server MCP-ready

npm install -g firma-app

Claude MCP visualizing finance data 

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

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.

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

Reviews (0)

No results found