@kimagure-dd/xirr-mcp

XIRR(확장 내부 수익률) 계산을 위한 MCP 서버로, 라쿠텐 증권(楽天証券) 거래 CSV를 기본 지원합니다.

Claude Desktop 또는 Claude Code에 연결하고 증권사에서 내보낸 CSV를 전달한 뒤 다음과 같이 질문하세요:

「이 CSV와 현재 평가액 ¥1,500,000으로 실적 연이율을 계산해 줘」

Claude가 불규칙한 입출금을 고려하여 XIRR을 계산하고 결과를 설명해 줍니다.

주요 기능

• 🧮 calculate_xirr — 임의의 현금 흐름 시리즈와 현재 평가액을 통한 XIRR 계산

• 📄 parse_rakuten_csv — 라쿠텐 증권 거래 내역(取引履歴) CSV를 정규화된 현금 흐름으로 파싱

• 🔌 순수 stdio MCP 서버, 네트워크 액세스 불필요

• 📦 런타임 설정 제로, 단일 npx 명령어로 실행

설치 및 설정

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하세요:

{
  "mcpServers": {
    "xirr": {
      "command": "npx",
      "args": ["-y", "@kimagure-dd/xirr-mcp"]
    }
  }
}

Claude Desktop을 재시작하세요. calculate_xirr 및 parse_rakuten_csv 도구가 나타나야 합니다.

Claude Code

claude mcp add xirr -- npx -y @kimagure-dd/xirr-mcp

사용 예시

직접 계산

Claude에게 다음과 같이 질문하세요:

「다음 현금 흐름으로 XIRR을 계산해 줘. 2020-01-01에 100만 엔 투자, 2022-01-01에 50만 엔 추가, 현재(2025-01-01) 평가액 200만 엔」

Claude가 구조화된 입력값으로 calculate_xirr을 호출하여 다음과 같이 반환합니다:

{
  "annualRate": 12.34,
  "annualRateFormatted": "12.34%",
  "totalInvestment": 1500000,
  "totalGain": 500000,
  "gainRateFormatted": "33.33%",
  "converged": true
}

라쿠텐 증권 CSV 사용

1. 라쿠텐 증권 로그인 → 거래 내역(取引履歴) → CSV 다운로드

2. (Shift_JIS로 다운로드되므로 UTF-8로 변환)

3. Claude에게 파일 내용을 전달하고 「이걸로 실적 연이율을 계산해 줘. 현재 평가액은 ¥X」라고 요청

Claude가 자동으로 CSV를 parse_rakuten_csv → calculate_xirr 순으로 파이프 처리합니다.

도구 참조

calculate_xirr

날짜별 현금 흐름 목록과 현재 평가액을 사용하여 XIRR을 계산합니다.

입력:

출력:

parse_rakuten_csv

라쿠텐 증권 거래 CSV를 파싱합니다.

입력:

필수 CSV 헤더:

約定日, 取引, ファンド名, 受渡金額/(ポイント利用)[円]

동작:

• 買付 행 → 양수(투자)

• 기타 거래 유형(예: 売却) → 음수(인출)

• 유효하지 않은 행은 경고와 함께 건너뜀

계산 방식

• 뉴턴-랩슨(Newton-Raphson) 반복법을 기본 솔버로 사용

• 뉴턴법 수렴 실패 시 이분법(Bisection)으로 대체

• 시간 단위: 월(월당 365.25 / 12일 사용)

• 수렴 임계값: 1e-7

kimagure-dd.dev의 브라우저 기반 XIRR 계산기와 동일한 로직을 사용하므로 결과가 동일합니다.

면책 조항

이 도구는 정보 제공 목적으로만 투자 성과를 계산합니다. 세금, 거래 수수료, 환전 비용은 고려되지 않습니다. 출력 결과는 투자 조언을 구성하지 않습니다.

개발

npm install
npm run build
npm test

배포 전 로컬에서 서버를 테스트하려면:

npm pack
# Then point Claude Desktop to the .tgz path

라이선스

MIT © kimagure-dd

관련 링크

• 🌐 kimagure-dd.dev — 브라우저 기반 금융 계산기

• 📊 XIRR 계산기 (웹 버전)

• 🐙 소스 코드