# @kimagure-dd/xirr-mcp

[![npm version](https://img.shields.io/npm/v/@kimagure-dd/xirr-mcp.svg)](https://www.npmjs.com/package/@kimagure-dd/xirr-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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):

```json
{
  "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

```bash
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:

```json
{
  "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](https://kimagure-dd.dev/tools/xirr-calculator), 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

```bash
npm install
npm run build
npm test
```

To test the server locally before publishing:

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

## License

MIT © kimagure-dd

## Related

- 🌐 [kimagure-dd.dev](https://kimagure-dd.dev) — Browser-based financial calculators
- 📊 [XIRR Calculator (web version)](https://kimagure-dd.dev/tools/xirr-calculator)
- 🐙 [Source code](https://github.com/kimagure-dd/xirr-mcp)