@Kimagure Dd/Xirr

npm version License: MIT

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 npx command

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

1. 楽天証券にログイン → 取引履歴 → CSV ダウンロード
2. (Shift_JIS でダウンロードされるため UTF-8 に変換)
3. 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