@kimagure-dd/xirr-mcp
MCP server for XIRR (Extended Internal Rate of Return) calculation, with built-in support for Rakuten Securities (楽天証券) transaction CSV.
Plug it into Claude Desktop or Claude Code, hand it a CSV exported from your brokerage, and ask:
「この CSV と現在の評価額 ¥1,500,000 で、実績年利を計算して」
Claude will compute the XIRR for you — accounting for irregular contributions and withdrawals — and explain the result.
Features
- 🧮
calculate_xirr— XIRR from arbitrary cash flow series + current valuation - 📄
parse_rakuten_csv— Parse Rakuten Securities transaction CSV (取引履歴) into normalized cash flows - 🔌 Pure stdio MCP server, no network access required
- 📦 Zero runtime config, single
npxcommand
Installation & Setup
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"xirr": {
"command": "npx",
"args": ["-y", "@kimagure-dd/xirr-mcp"]
}
}
}
Restart Claude Desktop. The calculate_xirr and parse_rakuten_csv tools should appear.
Claude Code
claude mcp add xirr -- npx -y @kimagure-dd/xirr-mcp
Usage Examples
Direct calculation
Ask Claude:
「以下のキャッシュフローで XIRR を計算して。2020-01-01 に 100万円投資、2022-01-01 に 50万円追加、現在（2025-01-01）の評価額 200万円」
Claude will call calculate_xirr with structured input and return:
{
"annualRate": 12.34,
"annualRateFormatted": "12.34%",
"totalInvestment": 1500000,
"totalGain": 500000,
"gainRateFormatted": "33.33%",
"converged": true
}
From Rakuten Securities CSV
- 楽天証券にログイン → 取引履歴 → CSV ダウンロード
- (Shift_JIS でダウンロードされるため UTF-8 に変換)
- Claude にファイル内容を渡して「これで実績年利を計算して。現在の評価額は ¥X」と依頼
Claude will pipe the CSV through parse_rakuten_csv → calculate_xirr automatically.
Tool Reference
calculate_xirr
Calculates XIRR from a list of dated cash flows and a current valuation.
Input:
| Field | Type | Description |
|---|---|---|
cashFlows | array | List of { date, amount }. Positive = invested, negative = withdrawn. |
currentValue | number | Current portfolio valuation. |
valuationDate | string | YYYY-MM-DD. Date of currentValue. |
Output:
| Field | Type | Description |
|---|---|---|
annualRate | number | Annualized return as a percentage. |
monthlyRate | number | Monthly rate (compounded to annual). |
totalInvestment | number | Sum of all cash flows. |
totalGain | number | currentValue - totalInvestment. |
gainRate | number | Total gain as a percentage of investment. |
converged | boolean | True if the iterative solver converged. |
parse_rakuten_csv
Parses a Rakuten Securities transaction CSV.
Input:
| Field | Type | Description |
|---|---|---|
csvContent | string | Raw CSV text (UTF-8 decoded). |
Required CSV headers:
約定日, 取引, ファンド名, 受渡金額/(ポイント利用)[円]
Behavior:
買付rows → positive amount (investment)- Other transaction types (e.g.
売却) → negative amount (withdrawal) - Invalid rows are skipped with warnings
Calculation Method
- Newton-Raphson iteration as the primary solver
- Bisection fallback when Newton fails to converge
- Time unit: months (using 365.25 / 12 days per month)
- Convergence threshold: 1e-7
The same logic is used in the browser-based XIRR calculator on kimagure-dd.dev, so results are identical.
Disclaimer
This tool computes investment performance for informational purposes only. Taxes, transaction fees, and currency conversion are not considered. The output does not constitute investment advice.
Development
npm install
npm run build
npm test
To test the server locally before publishing:
npm pack
# Then point Claude Desktop to the .tgz path
License
MIT © kimagure-dd
Related
- 🌐 kimagure-dd.dev — Browser-based financial calculators
- 📊 XIRR Calculator (web version)
- 🐙 Source code