Menu
マネーフォワードクラウド会計の公式MCP（mf-official）を使用する際のガイド。認証フロー、仕訳取得・登録、試算表・推移表の取得、科目マスタの扱い、金額計算の注意点など、MF公式MCPの全ツールの使い方とクセを網羅。「MFの仕訳」「マネーフォワードの試算表」「MF認証」「MFで仕訳登録」等のキーワードで発動。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | unofficial-official-mf-mcp-skill |
| description | マネーフォワードクラウド会計の公式MCP（mf-official）を使用する際のガイド。認証フロー、仕訳取得・登録、試算表・推移表の取得、科目マスタの扱い、金額計算の注意点など、MF公式MCPの全ツールの使い方とクセを網羅。「MFの仕訳」「マネーフォワードの試算表」「MF認証」「MFで仕訳登録」等のキーワードで発動。 |
MF公式MCPにはalpha版とbeta版の2つのエンドポイントがある。両方同時に.claude.jsonに登録可能。
| alpha版 | beta版 | |
|---|---|---|
| URL | https://alpha.mcp.developers.biz.moneyforward.com/mcp/ca/v3 | https://beta.mcp.developers.biz.moneyforward.com/mcp/ca/v3 |
| 認証方式 | 手動（認証コードをコピペ） | 自動（PKCE+localhostコールバック） |
| トークン有効期限 | 約1時間（頻繁に再認証が必要） | 長時間（詳細不明） |
| 複数法人同時利用 | ✅ 可能（法人ごとに認証して同時保持） | ❌ 1法人ずつ（切替時に再認証） |
| 手間 | 毎回コードコピペが面倒 | 認証はほぼワンクリック |
| ヘッドレス環境 | ✅ 対応（コードをチャット等で渡せばOK） | ❌ 不可（localhostリダイレクトが必要） |
使い分けの目安:
.claude.json の設定例{
"mcpServers": {
"mf-official-beta": {
"type": "http",
"url": "https://beta.mcp.developers.biz.moneyforward.com/mcp/ca/v3"
},
"mf-official-alpha": {
"type": "http",
"url": "https://alpha.mcp.developers.biz.moneyforward.com/mcp/ca/v3"
}
}
}
ツール名は .claude.json のサーバー名に依存する。上記設定例の場合:
mcp__mf-official-beta__authenticate, mcp__mf-official-beta__mfc_ca_getJournals 等mcp__mf-official-alpha__authenticate, mcp__mf-official-alpha__mfc_ca_getJournals 等本ガイドでは便宜上 mfc_ca_* とツール名のサフィックス部分のみで記載する。
authenticate ツールを呼び出すmfc_ca_* ツールが自動的に使えるようになる。access_tokenパラメータの手動指定も不要（サーバー側で自動管理）authenticate を実行するmfc_ca_authorize を呼び出す → 認証URLが生成されるmfc_ca_exchange で認可コードをアクセストークンに交換する（⚠️ この手順を飛ばすとAPI呼び出しが全て失敗する）mfc_ca_currentOffice 等のAPIが利用可能になる| カテゴリ | ツール | 用途 |
|---|---|---|
| 認証 | authenticate | OAuth認証（beta版はこれだけでOK） |
| 認証 | complete_authentication | beta版認証でlocalhostリダイレクトがエラーになった時のフォールバック（URLを貼り付けて認証完了） |
| 認証 | mfc_ca_authorize | 認証URL生成（alpha版ステップ1） |
| 認証 | mfc_ca_exchange | 認可コード→アクセストークン交換（alpha版ステップ2、必須） |
| 事業者 | currentOffice | 事業者情報・会計期間 |
| 事業者 | getTermSettings | 会計年度設定（税込/税抜・簡易課税/本則・都道府県・端数処理） |
| 仕訳 | getJournals / getJournalById | 仕訳取得 |
| 仕訳 | postJournals / putJournals | 仕訳登録・更新 |
| 試算表 | getReportsTrialBalanceBalanceSheet / ProfitLoss | 試算表（累計） |
| 推移表 | getReportsTransitionBalanceSheet / ProfitLoss | 推移表（月別） |
| マスタ | getAccounts / getSubAccounts / getDepartments / getTaxes | 科目・部門・税区分 |
| 取引先 | getTradePartners / postTradePartners | 取引先取得・登録 |
| 口座 | getConnectedAccounts | 手動管理の連携サービスのみ取得（⚠️自動取得側は返らない／明細は取れない） |
| 取引 | postTransactions | 明細の作成のみ（明細取得APIは存在しない） |
| 辞書 | en_ja_dictionary | 英日辞書 |
postVouchers（証憑アップロード）、deleteJournals（仕訳削除）、deleteVouchers（証憑の添付解除）はMCPツールスキーマには定義されていないが、アクセストークンで直接APIを叩けば利用可能。詳細は末尾の「スキーマ未定義だがAPIで利用可能な操作」参照。
getAccounts / getSubAccounts / getDepartments の available (boolean) クエリパラメータ（実測で挙動確定）:
OpenAPI仕様書の description は「nil」で記載がないが、2026-04に無効化済み科目を持つ事業者で3パターン実測した結果、以下の仕様が確定した:
| 指定 | 挙動 |
|---|---|
| 省略 | 有効な科目のみ返却（各レコードは available:true） |
available=true | 有効な科目のみ返却（省略時と同一） |
available=false | 全科目（有効+無効） を返却。無効化された科目は available:false で区別 |
名前と挙動が直感に反する点に注意:
false = 「無効な科目だけ」ではなく「全件（有効+無効）」false で取った後に available == false でフィルタする必要がある実務的な用途:
available=false を使うgetConnectedAccounts の実測仕様（重要）OpenAPI仕様書に明記されているが見落としやすい重要な制約:
/api/v3/connected_accounts: 連携サービスを取得します。明細を手動管理する連携サービスのみが返却されます。
返る項目: id と name の2フィールドだけ（残高・最終更新日・ステータス等は返らない）
返るサービス:
返らないサービス:
Transactions タグには postTransactions（作成）のみ存在。明細取得APIは存在しない）つまり:
実務的な用途:
postTransactions で明細を追加する際の connected_account_id 取得getReportsTrialBalance*）getReportsTransition*）end_month はカレンダー月を指定する（会計期の第N月目ではない）value は税抜き。税込 = value + tax_valuevalue は税込金額を指定する。APIが自動で税抜と消費税に分解するgetTermSettings）事業者の経理方式（税込/税抜）、課税方式（簡易/本則）、都道府県、端数処理等を一発で取得できる。
試算表APIを include_tax で2回叩いて比較する必要はない。
レスポンス例:
{
"term_settings": [
{
"accounting_method": "TAX_INCLUDED", // 税込経理
"tax_method": "SIMPLE", // 簡易課税
"business_types": ["OTHER"], // 業種区分
"prefecture": "鹿児島県",
"purchases_rounding_method": "ROUND_DOWN",
"sales_rounding_method": "ROUND_DOWN",
"fiscal_year": 2025,
"start_date": "2025-06-06",
"end_date": "2026-05-31"
}
]
}
| 値 | 意味 | 実測 |
|---|---|---|
TAX_INCLUDED | 税込経理 | ✅ サンプル法人A 2022年度以降 |
TAX_EXCLUDED_INCLUDED | 税抜経理（内税） | ✅ サンプル法人B、サンプル法人A 2021年度以前 |
TAX_EXCLUDED（推定、旧名称？） | 税抜経理（内税） | ❓ 実測では未出現、現行値は TAX_EXCLUDED_INCLUDED |
TAX_EXCLUDED_SEPARATE（推定） | 税抜経理（別記） | ❓ 未確認 |
| 値 | 意味 | 実測 |
|---|---|---|
INDIVIDUAL_ALLOCATION | 個別対応方式（本則課税の控除方式） | ✅ サンプル法人A / サンプル法人B |
SIMPLE（推定） | 簡易課税 | ❓ 未確認 |
GENERAL（推定） | 本則課税（一般課税） | ❓ 実測は INDIVIDUAL_ALLOCATION が返る |
EXEMPT（推定） | 免税 | ❓ 未確認 |
PROPORTIONAL（推定） | 一括比例配分方式 | ❓ 未確認 |
注: OpenAPI v3 で詳細化されているため、SKILL.md 初版の推定値と実 API 挙動が異なる。実測で確定した値のみ信頼すること。
簡易課税事業者の場合の業種区分。OTHER はその他。複数業種の会社は配列で複数持つ。
value + tax_value で帳簿金額）entered_by が JOURNAL_TYPE_OPENING の仕訳は期首残高。集計から除外すること仕訳を登録する前に必ず以下のマスタを取得しておくこと:
getAccounts → account_id を確認getSubAccounts → sub_account_id を確認getTaxes → tax_id を確認getDepartments → department_id を確認sub_account_id を省略すればよいDELETE /api/v3/journals/{id} → 204）。ただしMCPツールスキーマには未定義のため、直接APIを叩く必要があるputJournals は一部フィールドだけの部分更新ができない。branches, journal_type, transaction_date が必須で、仕訳全体を送り直す必要がある。
POST /api/v3/vouchers）。MCPツールスキーマには未定義だが、scopeに voucher.write が含まれておりAPIは存在するjournal_id を指定して証憑アップjournal_id なしでもアップ可能だが、孤立した証憑になり後から仕訳に紐づけるAPIは存在しないDELETE /api/v3/vouchers）は存在する。これは証憑自体を削除するのではなく、仕訳との紐付けを外すだけ（証憑は孤立した状態で残る）https://accounting.moneyforward.com/books?numbers={number}&recognized_at_from={期首日%2Fエスケープ}&recognized_at_to={期末日%2Fエスケープ}
department_name で集計するauthenticate で再認証し、別の事業者を選択する（beta版の場合）全仕訳のバックアップや一括集計が必要な場合は、recipes/bulk-journal-fetch.md の手順に従う。
scripts/merge_journals.py で結合MCPツールではなくREST APIを直接叩く場合（バッチ処理等）の注意事項。
https://api-accounting.moneyforward.com/api/v3
journal ID・account ID等のリソースIDはBase64エンコードされており、%2F（= /）を含むことがある。
このIDをURLパスにそのまま渡すと、サーバー側で %2F がスラッシュとしてデコードされ、パスが壊れて 403 forbidden になる。
対策: IDをURLパスに埋め込む前に quote(id, safe='') で全体を再エンコードすること。
from urllib.parse import quote
journal_id = quote(raw_id, safe='') # %2F → %252F, %3D → %253D 等
url = f"{BASE_URL}/journals/{journal_id}"
%2F だけ二重エンコードする方法は 400エラー になる（部分的な対処は不可）以下はMCPツールスキーマに定義されていないが、アクセストークンで直接APIを叩けば利用可能:
| 操作 | エンドポイント | メソッド | 備考 |
|---|---|---|---|
| 仕訳削除 | /api/v3/journals/{id} | DELETE | 204で成功。完全削除 |
| 証憑アップロード | /api/v3/vouchers | POST | journal_id指定で仕訳紐づけ |