mf-accounting-voucher-mcp

マネーフォワード クラウド会計の公式MCPサーバーが未対応の機能を補完するローカルMCPサーバーです。REST API v3 を直接呼び出し、公式MCP（リモート）と併用します。

提供ツール

ツール名	機能	APIエンドポイント
post_vouchers	証憑ファイル（PDF・画像）を仕訳に添付	POST /api/v3/vouchers
delete_voucher	証憑の添付解除	DELETE /api/v3/vouchers
delete_journal	仕訳の削除（取り消し不可）	DELETE /api/v3/journals/{id}

注記: 連携明細の「対象外」化は REST API に存在しないため提供しません。証憑ファイルのダウンロードも同様にAPI未対応です。公式MCPが提供済みの機能（getJournals 等）は再実装しません。

証憑ファイルのバイナリはLLMを経由しません。このサーバー（Nodeプロセス）がローカルのファイルパスを受け取り、読み込み・base64化してAPIへ送信します。

セットアップ

1. アプリポータルでアプリを登録

マネーフォワードのアプリポータルでアプリを作成し、以下を設定します。

• リダイレクトURI: http://127.0.0.1:53682/callback
• スコープ:
  • mfc/accounting/voucher.write（証憑の登録、削除）
  • mfc/accounting/journal.write（仕訳の登録、更新、削除）

発行された クライアントID / クライアントシークレット を控えます。

2. インストールとビルド

pnpm install && pnpm run build

3. 環境変数の設定

export MF_CLIENT_ID="（クライアントID）"
export MF_CLIENT_SECRET="（クライアントシークレット）"

変数	既定値	用途
MF_CLIENT_ID / MF_CLIENT_SECRET	なし（必須）	アプリポータルで発行
MF_REDIRECT_PORT	53682	コールバック用ローカルポート
MF_REDIRECT_URI	http://127.0.0.1:{PORT}/callback	リダイレクトURI
MF_TOKEN_PATH	~/.mf-accounting-voucher-mcp/tokens.json	トークン保存先
MF_MAX_FILE_MB	20	1ファイルの上限（ローカル側の安全弁）
MF_ALLOWED_EXT	.pdf,.jpg,.jpeg,.png	許可拡張子（カンマ区切りで上書き可）

4. 初回認可

pnpm run auth

ブラウザが開くので、マネーフォワードにログインして認可します。トークンは ~/.mf-accounting-voucher-mcp/tokens.json（mode 600）に保存され、以後は自動でリフレッシュされます。

Claude Desktop / Cowork への登録

一度登録すれば、クライアントの起動時にMCPサーバーは自動で立ち上がります。日常的に手動起動する操作は不要です。

推奨: キーチェーン利用（シークレットを設定ファイルに書かない）

初回のみ、認証情報をmacOSキーチェーンに登録します:

security add-generic-password -s mf-accounting-voucher-mcp -a client_id -w '（クライアントID）' -U
security add-generic-password -s mf-accounting-voucher-mcp -a client_secret -w '（クライアントシークレット）' -U

claude_desktop_config.json の mcpServers には起動スクリプトを登録します（パスは実際のインストール先に置き換えてください）:

{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "/path/to/mf-accounting-voucher-mcp/scripts/mf-accounting-voucher-mcp.sh",
      "args": []
    }
  }
}

初回OAuth認可もスクリプト経由で実行できます（環境変数の設定不要）:

scripts/mf-accounting-voucher-mcp.sh auth

代替: 環境変数を設定ファイルに直接書く

{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "node",
      "args": ["/path/to/mf-accounting-voucher-mcp/dist/index.js"],
      "env": {
        "MF_CLIENT_ID": "（クライアントID）",
        "MF_CLIENT_SECRET": "（クライアントシークレット）"
      }
    }
  }
}

この方法はシークレットが設定ファイルに平文で残る点に注意してください。

使用例

「この領収書（/Users/xxx/Downloads/receipt.pdf）を仕訳 XXXX に添付して」
→ post_vouchers が呼ばれ、添付結果（voucher_file_ids）が返る

「仕訳 XXXX の証憑 a60cd25d-... の添付を解除して」
→ delete_voucher

「仕訳 XXXX を削除して」
→ delete_journal（実行前に仕訳内容の提示と明示的な確認が入る）

添付結果は公式MCPの getJournalById で対象仕訳を取得し、voucher_file_ids に反映されていることで検証できます。

注意

• MFのファイル種別・サイズ・枚数の正確な制限は公式仕様書 /specs/vouchers を参照してください（本サーバーの上限はローカル側の安全弁です）
• 事業者（オフィス）の切り替えは pnpm run auth の再実行で行います
• delete_journal は取り消しできません。呼び出し側（LLM）はユーザーの明示的な確認を取ってから実行する設計です