mf-full-mcp
mf-full-mcp
머니포워드 클라우드 회계의 비공식 MCP 서버입니다. 공식 beta MCP와 동일한 이름의 도구(mfc_ca_*)를 제공하면서 다음 3가지를 추가했습니다.
증빙 첨부 — 영수증이나 청구서를 업로드하여 분개에 연결합니다. 공식 원격 MCP에는 2026년 8월 기준 이 기능이 없습니다
복수 사업자 동시 연결 — 복수 법인분 토큰을 보유하고, 재인증 없이 창/세션별로 다른 사업자에 연결할 수 있습니다
분개 완전 삭제 — 공식 MCP는 등록·갱신만 가능하며 삭제를 지원하지 않습니다
회계사무소처럼 일상적으로 수십 개 업체의 장부를 오가는 사용을 상정하고 있습니다.
비공식 프로젝트입니다. 주식회사 머니포워드와는 전혀 관계가 없습니다. 동사의 지원 대상이 아닙니다.
만든 이유
MF의 액세스 토큰은 인가 화면에서 선택한 1개 사업자에 연결됩니다(/api/v3/offices가 배열이 아닌 단일 객체를 반환하는 것이 그 증거입니다). 복수 법인을 다루려면 그 수만큼 토큰을 가질 필요가 있습니다.
공식 원격 MCP에는 2개의 엔드포인트가 있으며 각각 사정이 다릅니다.
공식 beta | 공식 alpha | 본 서버 | |
복수 법인 동시 보유 | 불가(전환 시 재인증) | 가능 | 가능 |
토큰 수명 | 장시간 | 약 1시간 | 자동 리프레시(실측 1개월 이상 방치 가능) |
인증 조작 | 자동 | 인증 코드를 수동으로 복사·붙여넣기 | 자동 |
증빙 첨부 | 불가 | 불가 | 가능 |
beta 버전은 인증이 쉬운 대신 1개 사업자만 보유할 수 있고, alpha 버전은 복수 보유가 가능한 대신 토큰이 약 1시간 만에 만료되어 수동 재인증이 필요합니다.
"복수 법인을, 재인증에 시달리지 않고, 창마다 별도로 다룬다"는 상태는 공식 어느 쪽으로도 성립하지 않습니다. 본 서버는 OAuth를 자체적으로 보유하여 이 부분을 메웁니다.
Related MCP server: MF Invoice MCP
설계상의 포인트
1. OAuth를 자체 보유(동적 클라이언트 등록)
RFC 7591의 동적 클라이언트 등록으로 인증할 때마다 공개 클라이언트를 등록합니다(token_endpoint_auth_method: "none" + PKCE).
따라서 사전 앱 등록이 불필요하고 client_secret이 애초에 존재하지 않습니다. 이 리포지토리에도, 이용자 환경에도 비밀키류는 전혀 배치되지 않습니다.
2. 사업자별로 토큰을 라벨 붙여 저장
~/.mf-full-mcp/tokens.json(디렉터리 0700/파일 0600)에 라벨을 키로 하여 복수 사업자분 토큰을 보유합니다. 토큰 1개=1개 사라면 필요한 만큼만 가지면 된다는 생각입니다.
만료는 자동으로 리프레시됩니다(만료 60초 전 선제 대응+401 시 1회 재시도). 실측에서는 리프레시 토큰이 1개월 이상 유효하여 한 번 인증하면 한동안 방치할 수 있습니다.
3. 활성 사업자는 "세션별"로 독립
이 프로젝트의 핵심입니다.
use_office로 전환되는 것은 프로세스 내 메모리뿐이며, 공유 파일의 active는 덮어쓰지 않습니다. 공유 파일의 값은 아직 한 번도 전환하지 않은 신규 프로세스의 초기값으로만 읽힙니다.
결과적으로 창 A에서 갑사, 창 B에서 을사를 병행하여 조작할 수 있습니다.
만약 여기서 공유 파일을 덮어썼다면, 한쪽이 사업자를 전환하는 순간 다른 쪽이 다른 법인의 데이터를 가져오게 됩니다. 장부를 다루는 이상 이는 절대 일어나서는 안 되는 사고입니다. "복수 사업자 동시 연결"의 실체는 토큰을 복수로 가질 수 있다는 것보다 활성 상태를 공유하지 않는 것에 있습니다.
기동 시 고정하고 싶다면 환경 변수 MF_FULL_OFFICE를 사용하세요.
4. 콜백 포트는 자동 할당
server.listen(0)으로 OS에 빈 포트를 할당시키고, 확정된 포트로 redirect_uri를 조립한 후에 클라이언트 등록합니다(RFC 8252의 loopback redirect).
고정 포트라면 두 번째 창에서의 인증이 EADDRINUSE로 실패합니다. "listen → 포트 확정 → register → authorize"라는 순서가 3의 설계를 실제로 기능하게 하기 위해 필요했습니다.
하위 호환을 위해 MF_FULL_CALLBACK_PORT를 명시했을 때만 고정 포트를 사용합니다.
증빙 첨부
공식 원격 MCP가 제공하는 도구는 2026년 8월 기준 분개·장표·명세·마스터 조작까지이며, 증빙(영수증·청구서)을 다루는 도구는 포함되어 있지 않습니다. 증빙을 분개에 연결하고 싶다면 브라우저에서 수작업할 수밖에 없었습니다.
본 서버는 이를 도구로 제공합니다. 로컬 파일의 절대 경로를 전달하기만 하면 base64화부터 업로드, 분개 첨부까지 수행합니다.
mfc_ca_postVouchers(journal_id: "<仕訳ID>", file_paths: ["/path/to/receipt.pdf"])연결을 해제하고 싶다면 mfc_ca_deleteVouchers를 사용합니다.
"분개를 작성하고, 대응하는 영수증을 첨부한다"까지를 하나의 흐름으로 완결할 수 있다는 것이 이 서버를 만든 동기 중 하나입니다.
주의 —
journal_id를 생략하면 어떤 분개에도 연결되지 않는 고립 증빙이 되며, 나중에 분개에 연결할 수단이 없습니다. 원칙적으로 반드시 지정하세요.
필요 환경
Node.js 20 이상
머니포워드 클라우드 회계 계정
설치
git clone https://github.com/kentaroajisaka/mf-full-mcp.git
cd mf-full-mcp
npm install
npm run buildMCP 클라이언트에 등록합니다(Claude Code의 경우 ~/.claude.json).
{
"mcpServers": {
"mf-full": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mf-full-mcp/dist/index.js"],
"env": {}
}
}
}사용법
1번째 사업자 인증
authenticate(label: "company-a")반환된 authUrl을 브라우저에서 열고 사업자를 선택하여 허가합니다. 완료되면 auth_status로 확인합니다.
2번째 이후 사업자 추가
같은 절차를 다른 라벨로 반복하기만 하면 됩니다.
authenticate(label: "company-b")연결 대상 전환
list_offices 保存済み事業者の一覧
use_office このセッションの接続先を切り替える
mfc_ca_currentOffice いまどの事業者に繋がっているか確認するuse_office는 다른 세션에 영향을 주지 않습니다. 데이터를 가져오기 전에 mfc_ca_currentOffice로 대상 법인을 확인하는 운용을 권장합니다.
도구 목록
인증·사업자 관리
도구 | 설명 |
| OAuth 인증을 시작합니다( |
| 진행 중인 인증 흐름의 상태를 확인합니다 |
| 저장된 사업자와 현재 연결 대상을 표시합니다 |
| 이 세션의 연결 대상을 전환합니다 |
| 저장된 토큰을 삭제합니다 |
| 요구 스코프·콜백 포트 등의 설정을 표시합니다 |
공식 MCP 호환(mfc_ca_*)
사업자·회계 기간, 계정과목, 보조과목, 부문, 세목구분, 거래처, 연계 서비스, 분개의 취득/등록/갱신, 시산표(BS·PL), 추이표(BS·PL), 명세의 취득/작성/분개화.
공식 MCP가 제공하지 않는 것
도구 | 설명 |
| 증빙을 업로드하여 분개에 첨부합니다(로컬 파일 경로를 전달하면 자동으로 base64화) |
| 분개와 증빙의 연결을 해제합니다(증빙 자체는 고립된 채 남음) |
| 분개를 완전 삭제합니다 |
환경 변수
변수 | 기본값 | 설명 |
| 없음 | 기동 시 세션의 연결 대상 사업자를 고정합니다 |
| 자동 할당 | OAuth 콜백 포트를 고정합니다 |
| 회계 16개 스코프 | 요구 스코프를 덮어씁니다 |
|
| 동적 클라이언트 등록 시 클라이언트 이름 |
알려진 주의점
MF의 API에는 몇 가지 밟기 쉬운 함정이 있습니다.
ID 인코딩 — MF의 ID는 Base64 유래로
%2F등을 포함합니다. URL 경로에 넣을 때 재인코딩하지 않으면 경로가 깨져 403이 됩니다. 본 서버는 대책이 적용되어 있지만, 반환된 ID는 가공하지 말고 그대로 전달하세요.putJournals는 전체 치환 — 부분 갱신은 불가능합니다. 갱신 전에 원래 분개를 백업해 두세요.쓰기 계열 도구의 취급 — 분개의 등록·갱신, 증빙의 첨부·해제, 명세의 분개화는 장부를 바꿉니다. AI 에이전트에서 사용할 경우 실행 전에 반드시 인간의 승인을 거치는 운용으로 하세요.
보안
토큰을 어디에 둘까
공식 원격 MCP는 인증이 서버 측에서 완결됩니다. 인가와 토큰 교환이 MCP 도구로 제공되어 이용자가 access_token을 직접 다룰 일이 없습니다. 즉 MF 토큰이 이용자 단말기에 놓이는 일이 없습니다.
본 서버는 반대로 토큰을 자신의 단말기에 보유합니다. ~/.mf-full-mcp/tokens.json에 평문으로 저장됩니다(디렉터리 0700/파일 0600).
이것은 트레이드오프입니다. 복수 법인분을 재인증 없이 보유할 수 있는 것도, 만료를 자동 갱신하여 한동안 방치할 수 있는 것도 리프레시 토큰이 곁에 있기 때문에 성립합니다. 반대로 말하면 이 파일이 유출되면 저장된 모든 사업자의 장부에 접근됩니다.
그 위에서 다음 운용을 전제로 합니다.
디스크가 암호화된 개인 단말기에서 사용할 것. 공용 단말기에서는 사용하지 말 것
불필요해진 사업자는
remove_office로 삭제할 것OS 키체인 저장은 향후 과제입니다
client_secret은 존재하지 않습니다
동적 클라이언트 등록으로 비밀키를 보관할 필요가 없는 설계입니다. 이 리포지토리에도, 이용자 환경에도 client_secret은 배치되지 않습니다.
면책
본 소프트웨어는 비공식이며 주식회사 머니포워드와 관계가 없습니다.
본 서버가 요구하는 스코프의 일부는 MF 측 사양 변경으로 예고 없이 이용할 수 없게 될 가능성이 있습니다. 그 경우 증빙 주변 등 일부 기능이 동작하지 않게 됩니다.
회계 장부라는 성질상 이용에 있어 다음 사항에 유의하세요.
쓰기 조작 결과에 대해 저자는 어떠한 책임도 지지 않습니다
본계 장부에서 사용하기 전에 테스트 사업자로 동작을 확인하세요
이용에 있어서는 머니포워드 이용약관을 각자 확인하세요
MIT 라이선스로 제공됩니다. 자세한 내용은 LICENSE를 참조하세요.
관련
unofficial-official-mf-mcp-skill — 공식 MCP 사용법·API 특성을 AI에 가르치는 비공식 스킬
mfc-journal-analyst-pro — 분개 분석·인계 자료 생성의 비공식 스킬
Available Tools
29 toolsauthenticateA
MFへのOAuth認証を開始する。返ってきたauthUrlをユーザーがブラウザで開き、事業者を選択して許可すると自動でトークンが保存される。完了確認はauth_status。
Inputs: label, extra_scopes.
auth_statusA
進行中の認証フローの状態を確認する(waiting/exchanging/done/error)。
Inputs: no named parameters.
list_officesA
保存済みトークン(事業者)の一覧とアクティブな接続先を表示する。
Inputs: no named parameters.
mfc_ca_currentOfficeB
事業者情報と会計期間を取得します。
Inputs: no named parameters.
mfc_ca_deleteJournalsA
仕訳を完全削除します(公式MCP未提供・帳簿書き込み。要ユーザー承認)。
Inputs: id (required).
mfc_ca_deleteVouchersA
仕訳と証憑の紐付けを解除します(証憑自体は孤立して残る。公式MCP未提供・要ユーザー承認)。
Inputs: journal_id (required), voucher_file_id (required).
mfc_ca_getAccountsC
勘定科目を取得します。
Inputs: available.
mfc_ca_getConnectedAccountsB
連携サービス(自動連携・手動管理とも)を取得します。
Inputs: no named parameters.
mfc_ca_getDepartmentsB
部門を取得します。
Inputs: available.
mfc_ca_getJournalByIdB
仕訳を1件取得します。
Inputs: id (required).
mfc_ca_getJournalsB
仕訳一覧を取得します。start_date または end_date のいずれかが必要。
Inputs: page, end_date, per_page, account_id, +3 more.
mfc_ca_getReportsTransitionBalanceSheetB
貸借対照表の推移表(月別)を取得します。
Inputs: type (required), end_month, fiscal_year, include_tax, +2 more.
mfc_ca_getReportsTransitionProfitLossC
損益計算書の推移表(月別)を取得します。
Inputs: type (required), end_month, fiscal_year, include_tax, +2 more.
mfc_ca_getReportsTrialBalanceBalanceSheetB
貸借対照表の試算表(累計)を取得します。
Inputs: end_date, end_month, start_date, fiscal_year, +4 more.
mfc_ca_getReportsTrialBalanceProfitLossC
損益計算書の試算表(累計)を取得します。
Inputs: end_date, end_month, start_date, fiscal_year, +4 more.
mfc_ca_getSubAccountsC
補助科目を取得します。
Inputs: available.
mfc_ca_getTaxesC
税区分を取得します。
Inputs: available.
mfc_ca_getTermSettingsA
会計年度設定(税込/税抜・課税方式等)を取得します。
Inputs: no named parameters.
mfc_ca_getTradePartnersC
取引先を取得します。
Inputs: available.
mfc_ca_getTransactionsB
連携サービスで収集された明細一覧を取得します(自動連携・手動とも)。
Inputs: end_date (required), start_date (required), page, side, +9 more.
mfc_ca_postJournalsB
仕訳を作成します(帳簿書き込み。要ユーザー承認)。
Inputs: journal (required).
mfc_ca_postTradePartnersB
取引先を作成します。
Inputs: trade_partner (required).
mfc_ca_postTransactionJournalizeA
明細から仕訳を作成します(帳簿書き込み。要ユーザー承認)。相手科目account_idのみ必須。貸借方向・口座側科目・税区分・invoice_kindはMFが自動補完。
Inputs: account_id (required), transaction_id (required), memo, tags, +7 more.
mfc_ca_postTransactionsA
手動管理の連携サービスに明細を作成します(要ユーザー承認)。
Inputs: transactions (required), connected_account_id (required).
mfc_ca_postVouchersA
証憑をアップロードし仕訳に添付します(公式MCP未提供・要ユーザー承認)。file_paths を渡せばローカルファイルを自動でbase64化する。journal_id 省略時は孤立証憑になる(後から仕訳に紐づける手段はない)ので原則指定すること。
Inputs: file_paths, journal_id, voucher_files.
mfc_ca_putJournalsA
仕訳を更新します(全置換API・帳簿書き込み。要ユーザー承認)。
Inputs: id (required), journal (required).
mf_full_infoB
このサーバーの設定情報(要求スコープ・コールバックポート等)を表示する。
Inputs: no named parameters.
remove_officeC
保存済みトークンを削除する。
Inputs: label (required).
use_officeA
このセッションのアクティブな接続先事業者を切り替える(プロセス内メモリのみ。他セッション/他ウィンドウには影響しない)。
Inputs: label (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Most tools have clear resource/action separation: journals, transactions, reports, master data, auth, and office management each have distinct targets. A few pairs like currentOffice vs list_offices or postJournals vs postTransactionJournalize have some boundary overlap, but the descriptions are precise enough to resolve most ambiguity.
The dominant mfc_ca_get/post/put/delete + Resource pattern is readable and consistent within the core accounting tools. However, the server mixes styles: verbless mfc_ca_currentOffice, un-prefixed snake_case names like remove_office and list_offices, and bare verbs like authenticate.
29 tools is a heavy surface and exceeds the 25+ threshold. Although the tools are grouped into clear subdomains such as journals, reports, master data, and auth, the high number of parallel getters and report variants creates meaningful selection overhead for agents.
Core workflows are well covered: authentication, office switching, journal CRUD, report retrieval, and master data reads are all present. Obvious gaps remain, however: trade partners have no update/delete, transactions have no update/delete, and vouchers lack list/get or an attach-orphan recovery path.
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server for ABRA Flexi — accounting, contacts, stock and draft-checked invoice creation.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server for Mekari Jurnal — company accounting, sales, purchases and customer/vendor creation.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAn MCP server and Claude plugin that enables interaction with freee APIs for accounting, human resources, invoicing, and more. It provides secure OAuth 2.0 authentication and integrates detailed API reference skills to support tasks like creating invoices and managing company data through natural language.21,715 npm521Apache 2.0
- AlicenseBqualityDmaintenanceAn MCP server that integrates with MoneyForward Cloud Invoice API v3 to automate the creation and management of quotes and invoices. It supports Japanese invoice system compliance, allowing users to handle partners, items, and billing through natural language.221MIT
- FlicenseNot gradedqualityDmaintenanceAn unofficial MCP server that integrates with the hokan Insurance CRM API v2 to manage customer data, schedules, and tasks. It also features specialized tools for Japanese insurance law compliance, including intent confirmation and regulatory check generation.-
- FlicenseAqualityCmaintenanceUnofficial MCP server for accessing and managing TimeTree calendar data, supporting events, memos, and comments via email/password authentication.6-