설치

Firma는 약 5분이면 시작할 수 있습니다. Node.js 22 이상, Claude Desktop, 그리고 Finnhub과 FRED 무료 계정이 필요합니다.

필수 요구 사항

Node.js 22 이상

node --version으로 확인합니다. nodejs.org에서 직접 설치하거나 nvm, brew install node로 설치할 수 있습니다.

Claude Desktop

MCP 연동에 필요합니다. Firma는 Claude가 호출할 수 있는 MCP 서버로 자신을 등록합니다. claude.ai/download에서 다운로드하세요.

Finnhub API 키 (무료)

가격 동기화, 실적 발표, 내부자 거래, 재무제표, 뉴스에 사용됩니다. finnhub.io에서 가입하세요. 무료 플랜으로 충분합니다.

FRED API 키 (무료)

거시경제 지표(VIX, 수익률 곡선, 달러 인덱스 등)와 과거 환율 캐시에 사용됩니다. 과거 환율 캐시는 USD가 아닌 통화로 입력된 항목을 정확하게 표시하는 데 필요합니다. fred.stlouisfed.org에서 가입하세요. 발급은 즉시 이뤄집니다.

설치 단계

전역 설치

npm install -g firma-app

두 개의 바이너리가 설치됩니다: firma (CLI)와 firma-mcp (MCP 서버).

API 키 등록

firma config set finnhub-key YOUR_KEYfirma config set fred-key YOUR_KEY

Finnhub 키는 finnhub.io/dashboard에서 발급받습니다. FRED 키는 fred.stlouisfed.org에서 발급받습니다. 두 곳 모두 무료입니다.

Claude Desktop 연결

firma mcp install

Claude Desktop의 설정 파일(macOS 기준 ~/Library/Application Support/Claude/claude_desktop_config.json)에 MCP 서버 항목을 기록합니다. 다시 시작하면 바로 활성화됩니다.

보유 자산 알려주기

Claude Desktop을 엽니다. 상단 도구 모음에 firma 도구가 보이면 정상입니다. CSV, 증권사 거래 내역, 스크린샷을 채팅창에 첨부하거나 보유 자산을 간단히 설명한 뒤 Firma 셋업을 요청합니다:

"[trades.csv 첨부] 이걸로 firma 셋업해줘. 그다음에 가격이랑 환율 동기화하고 포트폴리오 보여줘."

Claude는 각 행에 대해 add_txn을 호출한 뒤, sync_prices와 sync_fx_rates를 실행하고 show_portfolio로 결과를 보여줍니다. 온보딩 과정에서 CLI 명령어를 직접 입력할 필요가 없습니다. 자산과 현금흐름 가져오기 예시는 Importing Data (영문)에서 볼 수 있습니다.

일상적 사용

초기 셋업 후에는 하루 한 번 Claude에게 브리핑을 요청하면 됩니다:

"전체 동기화하고 오늘 브리핑 줘."

Claude는 sync_prices와 sync_fx_rates를 실행한 뒤 (첫 실행 이후 증분 동기화는 1초 미만 소요), get_brief를 호출합니다. 응답에는 비중이 포함된 보유 종목, 당일 P&L, 뉴스, 다가오는 실적 발표, 거시경제 컨텍스트, 사전 분석된 인사이트가 포함됩니다. Daily Brief (영문)에서 확인할 수 있습니다.

로컬 데이터

모든 데이터는 ~/.firma/firma.db (SQLite)와 ~/.firma/config.json에 저장됩니다. Firma 서버로 전송되는 데이터는 없습니다. 재무 이력을 보존하려면 ~/.firma/ 디렉터리를 백업해 두면 됩니다.

SQLite 파일은 어떤 SQLite 클라이언트로도 열 수 있습니다. 데이터를 독자적인 형식에 가두지 않습니다.

프로젝트 응원

Firma가 도움이 됐다면 GitHub에 별을 눌러주세요. 다음 기능을 만들어 갈 큰 동력이 됩니다.

★Star on GitHub↗