# MF Invoice MCP
MoneyForward クラウド請求書 API v3 を使用した MCP プラグイン。インボイス制度対応の見積書・請求書の作成を自動化します。
## 機能
### 認証
- `mf_auth_status` - 認証状態の確認
- `mf_auth_start` - OAuth認証の開始
- `mf_auth_callback` - 認証コードでトークン取得
- `mf_refresh_token` - トークンのリフレッシュ
### 取引先
- `mf_list_partners` - 取引先一覧の取得
- `mf_get_partner` - 取引先詳細の取得
### 品目
- `mf_list_items` - 品目一覧の取得
- `mf_get_item` - 品目詳細の取得
### 見積書
- `mf_list_quotes` - 見積書一覧の取得
- `mf_get_quote` - 見積書詳細の取得
- `mf_create_quote` - 見積書の作成（インボイス対応）
- `mf_update_quote` - 見積書の更新
- `mf_download_quote_pdf` - 見積書PDFのURL取得
- `mf_convert_quote_to_billing` - 見積書を請求書に変換
### 納品書
> ⚠️ **注意**: v3 APIでは納品書作成エンドポイントが提供されていません。納品書が必要な場合はマネーフォワードのWebUIで作成してください。
### 請求書
- `mf_list_billings` - 請求書一覧の取得
- `mf_get_billing` - 請求書詳細の取得
- `mf_create_billing` - 請求書の作成（インボイス対応）
- `mf_create_billing_from_quote` - 見積書から請求書を作成
- `mf_update_billing` - 請求書の更新
- `mf_update_payment_status` - 入金状態の更新
- `mf_download_billing_pdf` - 請求書PDFのURL取得
## インボイス制度対応
本MCPはインボイス制度（適格請求書等保存方式）に対応しています。
### 消費税区分（excise）
請求書・見積書作成時に明細行ごとに消費税区分を指定します。
| 値 | 説明 |
|----|------|
| `ten_percent` | 10% |
| `eight_percent_as_reduced_tax_rate` | 軽減税率8% |
| `eight_percent` | 8% |
| `untaxable` | 対象外 |
| `non_taxable` | 非課税 |
### department_id
インボイス対応請求書の作成には取引先の`department_id`が必要です。本MCPでは`mf_create_billing`・`mf_create_quote`実行時に自動で取引先の部門情報を取得します。
## セットアップ
### 1. MoneyForward クラウドでAPIアプリケーションを作成
1. [MoneyForward クラウド](https://biz.moneyforward.com/)にログイン
2. 開発者設定からAPIアプリケーションを作成
3. Client ID と Client Secret を取得
4. リダイレクトURIを設定（例: `http://localhost:38080/callback`）
5. **クライアント認証方式を `client_secret_post` に設定**（重要）
> ⚠️ **注意**: クライアント認証方式はデフォルトで `client_secret_basic` になっていますが、本MCPでは `client_secret_post` 方式を使用しています。アプリケーション作成時に必ず変更してください。
### 2. 環境変数の設定
```bash
export MF_CLIENT_ID="your_client_id"
export MF_CLIENT_SECRET="your_client_secret"
export MF_CALLBACK_PORT="38080" # オプション（デフォルト: 38080）
```
**重要**: MoneyForwardのAPIアプリケーション設定で、リダイレクトURIに `http://localhost:38080/callback` を登録してください。
### 3. ビルド
```bash
npm install
npm run build
```
### 4. Claude Desktop への設定
`~/Library/Application Support/Claude/claude_desktop_config.json` に以下を追加:
#### npx を使用する場合（推奨）
```json
{
"mcpServers": {
"mf-invoice": {
"command": "npx",
"args": ["@tera911/mf-invoice-mcp"],
"env": {
"MF_CLIENT_ID": "your_client_id",
"MF_CLIENT_SECRET": "your_client_secret",
"MF_CALLBACK_PORT": "38080"
}
}
}
}
```
#### ローカルビルドを使用する場合
```json
{
"mcpServers": {
"mf-invoice": {
"command": "node",
"args": ["/path/to/mf-invoice-mcp/dist/index.js"],
"env": {
"MF_CLIENT_ID": "your_client_id",
"MF_CLIENT_SECRET": "your_client_secret",
"MF_CALLBACK_PORT": "38080"
}
}
}
}
```
### 5. 初回認証
1. Claude で `mf_auth_start` を実行
2. 表示されたURLをブラウザで開く
3. MoneyForward にログインして認可
4. 認証完了後、自動的にトークンが保存される
**注意**: 認証時はポート38080（またはMF_CALLBACK_PORTで指定したポート）が空いている必要があります。
## 使用例
### 見積書を作成して請求書に変換
```
User: A社への見積書を作成して
Claude: まず取引先を検索します。
[mf_list_partners で検索]
User: 見つかった。作成して。
Claude: [mf_create_quote で作成]
見積書を作成しました。
User: これで承認されたから請求書を作って
Claude: [mf_convert_quote_to_billing で変換]
見積書から請求書を作成しました。
```
### 見積書・納品書・請求書の3点セット
```
User: B社への見積書を作成して、承認されたら納品書と請求書も作って
Claude: [mf_create_quote で作成]
見積書を作成しました。
User: 承認された
Claude: [mf_convert_quote_to_billing で請求書作成]
請求書を作成しました。
⚠️ 納品書はv3 APIでは作成できません。
マネーフォワードのWebUIから作成してください。
```
### 過去の請求書を参照して新規作成（インボイス対応）
```
User: 先月B社に送った請求書と同じ内容で今月分を作成して
Claude: [mf_list_billings でB社の請求書を検索]
前月の請求書が見つかりました。同じ内容で作成しますか？
※インボイス対応のため消費税10%を適用します
User: はい
Claude: [mf_create_billing で作成（excise: ten_percent指定）]
請求書を作成しました。
```
## API制限
- レート制限: 1秒あたり3リクエストまで（自動で制御）
- 超過時は HTTP 429 が返され、自動でリトライ
## v3 API 制限事項
- **納品書作成**: v3 APIでは`/delivery_slips/from_quote`エンドポイントが提供されていません。納品書が必要な場合はWebUIで作成してください。
- **請求書作成**: インボイス対応の請求書作成には`/invoice_template_billings`エンドポイントを使用します（旧`/billings`へのPOSTは404エラー）。
## トークン保存場所
認証情報は `~/.config/mf-invoice-mcp/tokens.json` に保存されます。
## ライセンス
MIT
