---
title: 설치
description: Firma를 설치하는 방법은 세 가지입니다 — macOS·Windows 인스톨러(터미널 불필요)와 npm. 설치 후 동작 방식은 동일합니다.
---

export const requirements = [
  {
    icon: '1',
    title: 'Node.js 22 이상',
    desc: <><code>node --version</code>으로 확인합니다. <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a>에서 직접 설치하거나 <code>nvm</code>, <code>brew install node</code>로 설치할 수 있습니다.</>,
  },
  {
    icon: '2',
    title: 'Claude Desktop',
    desc: <>MCP 연동에 필요합니다. Firma는 Claude가 호출할 수 있는 MCP 서버로 자신을 등록합니다. <a href="https://claude.ai/download" target="_blank" rel="noopener noreferrer">claude.ai/download</a>에서 다운로드하세요.</>,
  },
  {
    icon: '3',
    title: 'Finnhub API 키 (무료)',
    desc: <>가격 동기화, 실적 발표, 내부자 거래, 재무제표, 뉴스에 사용됩니다. <a href="https://finnhub.io" target="_blank" rel="noopener noreferrer">finnhub.io</a>에서 가입하세요. 무료 플랜으로 충분합니다.</>,
  },
  {
    icon: '4',
    title: 'FRED API 키 (무료)',
    desc: <>거시경제 지표(VIX, 수익률 곡선, 달러 인덱스 등)와 과거 환율 캐시에 사용됩니다. 과거 환율 캐시는 USD가 아닌 통화로 입력된 항목을 정확하게 표시하는 데 필요합니다. <a href="https://fred.stlouisfed.org/docs/api/api_key.html" target="_blank" rel="noopener noreferrer">fred.stlouisfed.org</a>에서 가입하세요. 발급은 즉시 이뤄집니다.</>,
  },
];

export const steps = [
  {
    num: '1',
    title: '전역 설치',
    body: <>
      <code className="step-code">npm install -g @evan-moon/firma</code>
      <p style={{ marginTop: '0.4rem' }}>
        두 개의 바이너리가 설치됩니다: <code>firma</code> (CLI)와 <code>firma-mcp</code> (MCP 서버).
      </p>
    </>,
  },
  {
    num: '2',
    title: 'API 키 등록',
    body: <>
      <code className="step-code">firma config set finnhub-key YOUR_KEY</code>
      <code className="step-code" style={{ marginTop: '0.3rem' }}>firma config set fred-key YOUR_KEY</code>
      <p style={{ marginTop: '0.4rem' }}>
        Finnhub 키는 <a href="https://finnhub.io/dashboard" target="_blank" rel="noopener noreferrer">finnhub.io/dashboard</a>에서 발급받습니다.
        FRED 키는 <a href="https://fred.stlouisfed.org/docs/api/api_key.html" target="_blank" rel="noopener noreferrer">fred.stlouisfed.org</a>에서 발급받습니다.
        두 곳 모두 무료입니다.
      </p>
    </>,
  },
  {
    num: '3',
    title: 'Claude Desktop 연결',
    body: <>
      <code className="step-code">firma mcp install</code>
      <p style={{ marginTop: '0.4rem' }}>
        Claude Desktop의 설정 파일(macOS 기준 <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>)에 MCP 서버 항목을 기록합니다. 다시 시작하면 바로 활성화됩니다.
      </p>
    </>,
  },
  {
    num: '4',
    title: '보유 자산 알려주기',
    body: <>
      <p>
        Claude Desktop을 엽니다. 상단 도구 모음에 firma 도구가 보이면 정상입니다.
        CSV, 증권사 거래 내역, 스크린샷을 채팅창에 첨부하거나 보유 자산을
        간단히 설명한 뒤 Firma 셋업을 요청합니다:
      </p>
      <p style={{ marginTop: '0.5rem', fontStyle: 'italic', color: 'var(--fg)' }}>
        "[trades.csv 첨부] 이걸로 firma 셋업해줘. 그다음에 가격이랑 환율 동기화하고 포트폴리오 보여줘."
      </p>
      <p style={{ marginTop: '0.5rem' }}>
        Claude는 모든 행을 하나의 배열로 <code>add_txn</code>에 전달한 뒤,{' '}
        <code>sync</code>를 실행하고{' '}
        <code>show_portfolio</code>로 결과를 보여줍니다. 온보딩 과정에서
        CLI 명령어를 직접 입력할 필요가 없습니다. 자산과 현금흐름
        가져오기 예시는{' '}
        <a href="/docs/import">Importing Data (영문)</a>에서 볼 수 있습니다.
      </p>
    </>,
  },
  {
    num: '5',
    title: '일상적 사용',
    body: <>
      <p>초기 셋업 후에는 하루 한 번 Claude에게 브리핑을 요청하면 됩니다:</p>
      <p style={{ marginTop: '0.5rem', fontStyle: 'italic', color: 'var(--fg)' }}>
        "전체 동기화하고 오늘 브리핑 줘."
      </p>
      <p style={{ marginTop: '0.5rem' }}>
        Claude는 <code>sync</code>를 실행한 뒤
        (첫 실행 이후 증분 동기화는 1초 미만 소요),{' '}
        <code>get_brief</code>를 호출합니다. 응답에는 비중이 포함된 보유 종목,
        당일 P&amp;L, 뉴스, 다가오는 실적 발표, 거시경제 컨텍스트, 사전 분석된
        인사이트가 포함됩니다.{' '}
        <a href="/docs/brief">Daily Brief (영문)</a>에서 확인할 수 있습니다.
      </p>
    </>,
  },
];

<Section label="설치">
<div style={{display:'grid', gridTemplateColumns:'repeat(auto-fit, minmax(260px, 1fr))', gap:'1rem'}}>
  <div style={{background:'var(--subtle)', border:'1px solid var(--border)', borderRadius:'10px', padding:'1.25rem 1.5rem', display:'flex', flexDirection:'column', gap:'0.75rem'}}>
    <div style={{fontWeight:600, fontSize:'0.95rem'}}>macOS 인스톨러</div>
    <p className="docs-body">다운로드 후 더블클릭. Node.js가 내장되어 있어 별도 설치 불필요. Claude Desktop과 Claude Code 연동이 자동으로 완료되며, 설치 후 다이얼로그가 API 키 등록용 <code>firma config set</code> 명령 두 줄을 안내합니다.</p>
    <a href="https://github.com/evan-moon/firma/releases/latest/download/firma-mac-arm64.pkg" target="_blank" rel="noopener noreferrer" style={{display:'inline-flex', alignItems:'center', gap:'0.4rem', background:'var(--green)', color:'#0a0a0a', padding:'0.55rem 1.1rem', borderRadius:'7px', fontWeight:600, fontSize:'0.85rem', textDecoration:'none', width:'fit-content'}}>↓ firma-mac-arm64.pkg</a>
    <p style={{fontSize:'0.8rem', color:'var(--muted)', margin:0}}>다운로드 → 더블클릭 → 설치 안내 따르기 → Claude Desktop 재시작.</p>
  </div>
  <div style={{background:'var(--subtle)', border:'1px solid var(--border)', borderRadius:'10px', padding:'1.25rem 1.5rem', display:'flex', flexDirection:'column', gap:'0.75rem'}}>
    <div style={{fontWeight:600, fontSize:'0.95rem'}}>Windows 인스톨러</div>
    <p className="docs-body">다운로드 후 실행. Node.js가 내장되어 있고 <code>firma</code>가 <code>PATH</code>에 등록되어 별도 설치 불필요. Claude Desktop과 Claude Code 연동이 자동으로 완료되며, 설치 후 다이얼로그가 API 키 등록용 <code>firma config set</code> 명령 두 줄을 안내합니다.</p>
    <a href="https://github.com/evan-moon/firma/releases/latest/download/firma-win-x64.exe" target="_blank" rel="noopener noreferrer" style={{display:'inline-flex', alignItems:'center', gap:'0.4rem', background:'var(--green)', color:'#0a0a0a', padding:'0.55rem 1.1rem', borderRadius:'7px', fontWeight:600, fontSize:'0.85rem', textDecoration:'none', width:'fit-content'}}>↓ firma-win-x64.exe</a>
    <p style={{fontSize:'0.8rem', color:'var(--muted)', margin:0}}>서명되지 않은 설치 파일입니다 — SmartScreen 경고 시 추가 정보 → 실행을 선택하세요.</p>
  </div>
  <div style={{background:'var(--subtle)', border:'1px solid var(--border)', borderRadius:'10px', padding:'1.25rem 1.5rem', display:'flex', flexDirection:'column', gap:'0.75rem'}}>
    <div style={{fontWeight:600, fontSize:'0.95rem'}}>npm</div>
    <p className="docs-body">npm으로 설치합니다. Node.js 22 이상이 필요합니다. CLI와 MCP를 모두 사용할 수 있습니다.</p>
    <code className="step-code">npm install -g @evan-moon/firma</code>
    <p style={{fontSize:'0.8rem', color:'var(--muted)', margin:0}}>이후 API 키 등록과 <code>firma mcp install</code>을 실행합니다 — 아래 단계를 참고하세요.</p>
  </div>
</div>
</Section>

<Section label="npm 설치 단계">
  <FeatureList items={requirements} />
  <div style={{marginTop:'1.5rem'}}>
    <Steps items={steps} />
  </div>
</Section>

<Section label="로컬 데이터">
<div className="privacy">
  <div className="docs-body">
    모든 데이터는 <code>~/.firma/firma.db</code> (SQLite)와{' '}
    <code>~/.firma/config.json</code>에 저장됩니다. Firma 서버로 전송되는
    데이터는 없습니다. 재무 이력을 보존하려면{' '}
    <code>~/.firma/</code> 디렉터리를 백업해 두면 됩니다.
  </div>
  <div className="docs-body">
    SQLite 파일은 어떤 SQLite 클라이언트로도 열 수 있습니다.
    데이터를 독자적인 형식에 가두지 않습니다.
  </div>
</div>
</Section>

<Section label="프로젝트 응원">
<div className="docs-body">
  Firma가 도움이 됐다면 GitHub에 별을 눌러주세요. 다음 기능을 만들어 갈 큰 동력이 됩니다.
</div>
<a href="https://github.com/evan-moon/firma" className="star-cta" target="_blank" rel="noopener noreferrer">
  <span className="star-cta-icon">★</span>
  <span>Star on GitHub</span>
  <span className="star-cta-arrow">↗</span>
</a>
</Section>
