traygerbig ╔══════════════════════════════════════════════════════════════════╗
║ ║
║ $$\ $$\ $$$$$$\ $$\ $$\ $$$$$$$$\ $$\ $$\ ║
║ $$$\ $$$ |$$ __$$\ $$$\ $$ |$$ _____|$$ | $$ | ║
║ $$$$\ $$$$ |$$ / $$ |$$$$\ $$ |$$ | \$$\ $$ | ║
║ $$\$$\$$ $$ |$$ | $$ |$$ $$\$$ |$$$$$\ \$$$$ / ║
║ $$ \$$$ $$ |$$ | $$ |$$ \$$$$ |$$ __| \$$ / ║
║ $$ |\$ /$$ |$$ | $$ |$$ |\$$$ |$$ | $$ | ║
║ $$ | \_/ $$ | $$$$$$ |$$ | \$$ |$$$$$$$$\ $$ | ║
║ \__| \__| \______/ \__| \__|\________| \__| ║
║ ║
║ F O R W A R D A G E N T ║
║ Cloud Accounting from Your Terminal ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
skill: moneyforward-agent platform: MoneyForward protocol: OAuth2 REST lang: en/ja fintech: cloud
Automate your entire Japanese accounting workflow from the command line -- invoices, expenses, reconciliation, and tax reports on MoneyForward Cloud.
Overview
MoneyForward Agent transforms your terminal into a full-featured accounting workstation connected to Japan's most widely adopted cloud accounting platform. MoneyForward Cloud serves over 300,000 businesses in Japan, from solo freelancers filing blue-form returns to mid-market companies managing multi-entity consolidation. This agent provides direct API access to every core accounting function: creating and sending invoices, recording expenses, posting journal entries, reconciling bank transactions, and generating financial statements.
The Japanese accounting landscape has unique requirements -- consumption tax (shouhizei) with multiple rates (10% standard, 8% reduced), invoice system compliance (tekikaku invoice), fiscal year conventions, and integration with tax filing via e-Tax. MoneyForward Agent handles all of these natively. It supports the qualified invoice system (tekikaku seikyu-sho) mandated since October 2023, automatically calculates tax breakdowns, and formats reports to Japanese GAAP standards. The OAuth2 authentication flow ensures secure, token-based access with automatic refresh, and every mutation operation logs an audit trail for your tax advisor.
┌─────────────────────────────────────────────────────────────┐
│ MONEYFORWARD AGENT ARCHITECTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ Terminal CLI │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ Command │───▶│ OAuth2 Auth │───▶│ MF Cloud │ │
│ │ Router │ │ Token Mgmt │ │ API v3 │ │
│ └─────────────┘ └───────────────┘ └──────┬──────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ Invoice │ │ Expense │ │ Journal │ │
│ │ Engine │ │ Processor │ │ Entry Mgr │ │
│ └──────┬──────┘ └───────┬───────┘ └──────┬──────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ Bank Reconcile │ │
│ │ + Tax Compute │ │
│ └────────┬──────────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ PL / BS │ │ Tax Rpt │ │ CSV/PDF │ │
│ │ Reports │ │ e-Tax │ │ Export │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
System Prompt Instructions
When operating as the MoneyForward Agent, adhere to the following rules:
- Authenticate using OAuth2 with
MF_CLIENT_ID,MF_CLIENT_SECRET, andMF_REFRESH_TOKEN; auto-refresh access tokens before expiry. - Always include
MF_COMPANY_IDin API requests to scope operations to the correct business entity. - All monetary values must be displayed in JPY with comma separators (e.g., 1,234,567 JPY) unless the account uses a different currency.
- Consumption tax calculations must follow the qualified invoice system (tekikaku seikyu-sho) rules: 10% standard, 8% reduced rate.
- Invoice creation must validate the seller's registration number (T + 13 digits) for tekikaku compliance.
- Journal entries must use standard Japanese account codes (kanjou kamoku) mapped to MoneyForward's chart of accounts.
- Bank reconciliation must never auto-match transactions below 70% confidence; flag those for manual review.
- All dates must default to Japanese fiscal year conventions (April 1 to March 31) unless overridden.
- Expense submissions must attach receipt images when the amount exceeds 30,000 JPY (tax office requirement).
- Never delete invoices or journal entries without
--confirmflag; soft-delete (void) is preferred. - Export operations must include a header row with field names and encode output as UTF-8 with BOM for Excel compatibility.
- Partner (torihiki-saki) management must validate corporate numbers (houjin bangou) when provided.
- PL and BS reports must show comparison columns (current period vs. prior period) by default.
- Rate-limit API calls to 300 requests per 5-minute window; queue excess requests automatically.
- Log every financial mutation (create, update, void) to
~/.mf-agent/audit.logwith timestamp, user, and payload hash. - Display account balances with debit/credit indicators following Japanese bookkeeping conventions.
- Tax report generation must separate standard-rate and reduced-rate consumption tax automatically.
- Handle API pagination transparently; never truncate financial data silently.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
MF_CLIENT_ID |
Yes | -- | OAuth2 client ID from MF developer console |
MF_CLIENT_SECRET |
Yes | -- | OAuth2 client secret |
MF_REFRESH_TOKEN |
Yes | -- | Long-lived refresh token for automated access |
MF_COMPANY_ID |
Yes | -- | Target company/business entity ID |
Set these in your shell profile or .env file:
export MF_CLIENT_ID="mf_client_abc123"
export MF_CLIENT_SECRET="mf_secret_xyz789"
export MF_REFRESH_TOKEN="mf_refresh_token_long_string"
export MF_COMPANY_ID="comp_12345"
Commands
mf invoices -- List and filter invoices
$ mf invoices --status unpaid --period 2026-02
Invoices [status: unpaid, period: 2026-02]
══════════════════════════════════════════════════════════════
Invoice # Partner Issue Date Due Date Amount (JPY) Tax
──────────── ───────────────────────── ────────── ────────── ──────────── ────────
INV-2026-041 Sakura Design Inc. 2026-02-01 2026-03-31 550,000 50,000
INV-2026-043 Fujisan Trading Co. 2026-02-05 2026-03-31 1,320,000 120,000
INV-2026-047 Nihon Systems K.K. 2026-02-10 2026-03-31 880,000 80,000
INV-2026-052 Green Energy Partners 2026-02-15 2026-04-30 275,000 25,000
INV-2026-058 Tokyo Bay Logistics 2026-02-20 2026-04-30 2,200,000 200,000
── 5 unpaid invoices | Total: 5,225,000 JPY (tax: 475,000 JPY) ──
mf invoice-create -- Create and send a new invoice
$ mf invoice-create \
--partner "Sakura Design Inc." \
--items '[{"desc":"Web design","qty":1,"unit_price":500000,"tax_rate":10}]' \
--due 2026-04-30
Invoice Created
══════════════════════════════════════════════════════════════
Invoice #: INV-2026-063
Partner: Sakura Design Inc.
Reg. Number: T1234567890123 (tekikaku verified)
Issue Date: 2026-03-01
Due Date: 2026-04-30
Line Items:
─────────────────────────────────────────────────────────────
# Description Qty Unit Price Tax Rate Amount
1 Web design 1 500,000 10% 550,000
Subtotal: 500,000 JPY
Tax (10%): 50,000 JPY
Total: 550,000 JPY
Status: Draft
[TIP] Run: mf invoice-send INV-2026-063 to email to partner
── invoice created in 0.65s ──
mf expenses -- Manage expense claims
$ mf expenses --month 2026-02
Expense Report (February 2026)
══════════════════════════════════════════════════════════════
Date Category Vendor Amount (JPY) Receipt Status
────────── ──────────────── ─────────────────────── ──────────── ─────── ────────
2026-02-03 Transportation JR East (Suica charge) 12,400 auto Approved
2026-02-05 Entertainment Gonpachi Roppongi 35,200 img Approved
2026-02-08 Supplies Amazon Business 8,750 pdf Approved
2026-02-12 Transportation ANA (HND-ITM) 32,800 img Pending
2026-02-14 Communication Zoom Pro (monthly) 2,200 auto Approved
2026-02-18 Entertainment Imperial Hotel bar 48,600 img Pending
2026-02-22 Supplies Yodobashi Camera 15,400 img Approved
2026-02-27 Transportation Taxi (Uber Japan) 4,800 auto Approved
Total: 160,150 JPY
Approved: 124,750 JPY
Pending: 35,400 JPY (2 items awaiting approval)
── 8 expenses in period ──
mf journals -- View and create journal entries
$ mf journals --date 2026-02-28
Journal Entries (2026-02-28)
══════════════════════════════════════════════════════════════
Entry # Debit Account Credit Account Amount (JPY) Memo
───────── ────────────────────── ────────────────────── ──────────── ──────────────
JE-4201 売掛金 (Acct Recv) 売上高 (Revenue) 1,320,000 Fujisan Feb inv
JE-4202 通信費 (Communication) 未払金 (Acct Payable) 2,200 Zoom monthly
JE-4203 交際費 (Entertainment) 現金 (Cash) 35,200 Client dinner
JE-4204 仮払消費税 (Input Tax) 未払金 (Acct Payable) 3,520 Tax on JE-4203
── 4 entries on 2026-02-28 ──
mf reconcile -- Bank transaction reconciliation
$ mf reconcile --account "MUFG Main" --period 2026-02
Bank Reconciliation: MUFG Main (February 2026)
══════════════════════════════════════════════════════════════
Bank transactions: 142
Auto-matched: 128 (90.1%)
Suggested matches: 9 (confidence 70-89%)
Unmatched: 5 (manual review needed)
Unmatched Transactions:
─────────────────────────────────────────────────────────────
Date Description Amount (JPY) Direction
────────── ─────────────────────── ──────────── ─────────
2026-02-06 AMAZON MARKETPLACE -15,800 Debit
2026-02-11 PAYPAY TRANSFER +8,000 Credit
2026-02-16 ATM DEPOSIT +200,000 Credit
2026-02-21 SEVENELEVEN *1234 -1,230 Debit
2026-02-26 WIRE FROM UNKNOWN +55,000 Credit
Actions: mf reconcile --match JE-XXXX --txn TXN-YYYY
mf reconcile --ignore TXN-YYYY --reason "personal"
── reconciliation completed in 3.1s ──
mf reports -- Generate PL/BS financial statements
$ mf reports --type pl --period 2026-02
Profit & Loss Statement (February 2026)
══════════════════════════════════════════════════════════════
Account This Month Last Month YTD (Apr-Feb)
───────────────────────────── ────────────── ────────────── ──────────────
REVENUE
売上高 (Sales) 8,450,000 7,820,000 89,100,000
Other Revenue 120,000 150,000 1,340,000
───────────────────────────── ────────────── ────────────── ──────────────
Total Revenue 8,570,000 7,970,000 90,440,000
EXPENSES
仕入高 (COGS) 3,200,000 2,980,000 33,600,000
給料手当 (Payroll) 2,400,000 2,400,000 26,400,000
地代家賃 (Rent) 350,000 350,000 3,850,000
通信費 (Communication) 85,000 82,000 920,000
交際費 (Entertainment) 148,000 195,000 1,670,000
消耗品費 (Supplies) 62,000 45,000 580,000
その他 (Other) 125,000 118,000 1,280,000
───────────────────────────── ────────────── ────────────── ──────────────
Total Expenses 6,370,000 6,170,000 68,300,000
═══════════════════════════════════════════════════════════════
NET INCOME 2,200,000 1,800,000 22,140,000
═══════════════════════════════════════════════════════════════
── MoM change: +22.2% | YTD margin: 24.5% ──
mf partners -- Manage business partners (torihiki-saki)
$ mf partners --search "Sakura"
Partner Search Results
══════════════════════════════════════════════════════════════
ID Name Corp. Number Balance (JPY) Status
───────── ────────────────────── ────────────────── ────────────── ────────
P-001234 Sakura Design Inc. 4010001098765 550,000 (AR) Active
P-001567 Sakura Foods K.K. 1020001054321 -82,500 (AP) Active
P-002890 Sakura Tech Solutions 7030001076543 0 Inactive
── 3 results ──
mf tax -- Tax calculation and filing preparation
$ mf tax --type consumption --period 2025
Consumption Tax Report (FY2025: Apr 2025 - Mar 2026)
══════════════════════════════════════════════════════════════
OUTPUT TAX (売上に係る消費税)
Standard rate (10%): 7,840,000 JPY on 78,400,000 JPY sales
Reduced rate (8%): 480,000 JPY on 6,000,000 JPY sales
─────────────────────────────────────────────────────────────
Total Output Tax: 8,320,000 JPY
INPUT TAX (仕入に係る消費税)
Standard rate (10%): 5,120,000 JPY on 51,200,000 JPY purchases
Reduced rate (8%): 160,000 JPY on 2,000,000 JPY purchases
─────────────────────────────────────────────────────────────
Total Input Tax: 5,280,000 JPY
═══════════════════════════════════════════════════════════════
TAX PAYABLE: 3,040,000 JPY
═══════════════════════════════════════════════════════════════
Filing deadline: 2026-05-31 (2-month extension applied)
e-Tax ready: Yes (XML export available)
── Run: mf tax --export etax to generate filing XML ──
mf export -- Export financial data
$ mf export --type journals --period 2026-02 --format csv
Export: Journal Entries (February 2026)
══════════════════════════════════════════════════════════════
Records: 187
Format: CSV (UTF-8 with BOM)
Columns: date, entry_no, debit_account, credit_account, amount, tax, memo
Output: ./journals_2026-02.csv
[████████████████████████████████████████] 187/187
[OK] Exported 187 journal entries to journals_2026-02.csv (24.8 KB)
mf dashboard -- Real-time financial overview
$ mf dashboard
Financial Dashboard (as of 2026-03-01)
══════════════════════════════════════════════════════════════
Cash Position:
MUFG Main: 12,450,000 JPY
SMBC Operating: 3,200,000 JPY
PayPay Business: 185,000 JPY
─────────────────────────────────────────────────────────────
Total Cash: 15,835,000 JPY
Receivables: 5,225,000 JPY (5 unpaid invoices)
Payables: -2,180,000 JPY (8 outstanding bills)
MTD Revenue: 8,570,000 JPY (+7.5% vs last month)
MTD Expenses: 6,370,000 JPY (+3.2% vs last month)
MTD Net Income: 2,200,000 JPY
Upcoming:
Mar 10 Payroll run -2,400,000 JPY
Mar 15 Rent payment -350,000 JPY
Mar 31 Quarterly tax est. -1,520,000 JPY
── dashboard refreshed at 09:15 JST ──
Workflow Diagram
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Bank APIs │ │ Receipt │ │ Invoice │
│ (MUFG,SMBC) │ │ Scanner │ │ Incoming │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└────────────────────┼────────────────────┘
│
▼
┌─────────────────────┐
│ MoneyForward Agent │
│ (mf commands) │
└──────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Auto-match │ │ Categorize │ │ Post │
│ Bank Txns │ │ Expenses │ │ Journals │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└───────────────────┼───────────────────┘
│
▼
┌─────────────────────┐
│ Trial Balance │
│ Verification │
└──────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PL / BS │ │ Tax Filing │ │ Audit │
│ Reports │ │ (e-Tax XML) │ │ Export │
└──────────────┘ └──────────────┘ └──────────────┘
Error Handling
| Error | Cause | Solution |
|---|---|---|
OAUTH_EXPIRED: Refresh token invalid |
Token revoked or expired beyond 90 days | Re-authenticate via mf auth to generate a new refresh token |
COMPANY_NOT_FOUND: Invalid MF_COMPANY_ID |
Wrong company ID or insufficient permissions | Verify ID in MoneyForward settings; ensure API scope includes the target company |
INVOICE_VALIDATION: Missing registration number |
Tekikaku invoice requires seller T-number | Add T-number via mf partners --update P-XXXX --reg-number T1234567890123 |
RECONCILE_CONFLICT: Transaction already matched |
Bank txn linked to another journal entry | Use mf reconcile --unmatch TXN-XXXX first, then re-match |
TAX_RATE_MISMATCH: 8% applied to non-food item |
Reduced rate used on standard-rate goods | Edit journal entry tax rate; audit with mf tax --audit |
EXPORT_SIZE_LIMIT: >10,000 rows |
Export exceeds single-file limit | Split by period: --period 2026-01 and --period 2026-02 separately |
BALANCE_MISMATCH: Trial balance off by 1,230 JPY |
Rounding or missing entry | Run mf journals --unbalanced to find orphaned single-sided entries |
Data Storage
~/.moneyforward-agent/
├── config/
│ └── config.yaml # Company ID, preferences, API settings
├── cache/
│ ├── accounts.json # Chart of accounts cache (1-hour TTL)
│ ├── categories.json # Expense category cache
│ └── journals.json # Recent journal entries cache
├── tokens/
│ └── oauth2.json # Access/refresh tokens (encrypted at rest)
├── reports/
│ ├── monthly/ # Monthly PL/BS report archives
│ └── annual/ # Annual financial statement archives
├── exports/
│ └── csv/ # CSV/PDF/XML export output files
├── templates/
│ ├── invoice/ # Invoice templates
│ └── expense/ # Expense report templates
├── reconciliation/
│ └── cache/ # Bank txn matching state (30-day retention)
└── logs/
└── audit.log # Financial mutation log (7-year retention)
OAuth tokens are encrypted at rest. The audit log uses append-only writes to prevent tampering. Financial exports should be stored according to your organization's document retention policy (typically 7 years for Japanese tax law compliance).
Comparison Table
| Feature | MF Agent (CLI) | MF Web UI | freee | Yayoi Online | QuickBooks |
|---|---|---|---|---|---|
| Invoice creation | CLI + template | Web form | Web form | Web form | Web form |
| Tekikaku invoice | Native | Native | Native | Native | No |
| Bank reconciliation | Auto + manual | Auto + manual | Auto | Semi-auto | Auto |
| Journal entry | Direct CLI post | Web form | Web form | Import only | Web form |
| Consumption tax calc | Dual-rate auto | Dual-rate auto | Auto | Auto | US sales tax |
| e-Tax XML export | Yes | Yes | Yes | Yes | No |
| CLI/scripting | Full automation | No | Limited API | No | Limited |
| Japanese GAAP | Native | Native | Native | Native | US GAAP |
| Multi-entity | Per company ID | Per login | Per login | Per login | Per subscription |
| Batch operations | Yes (pipe/script) | Manual | No | No | No |
| Offline access | Cached data | No | No | No | No |
| Setup time | 5 minutes | N/A | N/A | N/A | N/A |
FAQ
Q1: How do I obtain OAuth2 credentials for MoneyForward API? Register a developer application at MoneyForward Developer Portal. You will receive a client ID and secret. Use the authorization code flow to get your initial refresh token.
Q2: Can I manage multiple companies with one agent?
Yes. Switch between companies using mf config --company comp_67890 or pass --company to any command.
Q3: How does the tekikaku invoice validation work? The agent verifies the seller's T-registration number against MoneyForward's registry. If the number is missing or invalid, invoice creation will warn you but still allow draft creation.
Q4: Is the audit log tamper-proof? The audit log uses append-only writes with SHA-256 hashes chaining each entry. While not blockchain-level immutable, it provides strong evidence for tax audits.
Q5: Can I automate monthly closing?
Yes. Script the workflow: mf reconcile --auto && mf journals --post-accruals && mf reports --type pl --type bs && mf export --type trial-balance.
Q6: How does bank API reconciliation work? MoneyForward connects to 2,600+ Japanese financial institutions via account aggregation. The agent pulls transaction data and matches against journal entries using amount, date, and payee heuristics.
Q7: What happens if a reconciliation match is wrong?
Use mf reconcile --unmatch TXN-XXXX to break the link. The transaction returns to the unmatched queue for re-assignment.
Q8: Can I create recurring invoices?
Yes. Use mf invoice-create --recurring monthly --partner "Partner Name" to set up automatic monthly invoice generation.
Q9: How are reduced-rate items handled?
Items tagged with food/beverage categories automatically use the 8% reduced rate. Override with --tax-rate 8 or --tax-rate 10 per line item.
Q10: Does the agent support payroll integration?
Payroll is managed through MoneyForward Payroll (a separate product). Journal entries from payroll can be imported via mf journals --import payroll.
Q11: Can I generate reports for a custom date range?
Yes. Use --from 2025-10-01 --to 2026-02-28 on any report command for arbitrary date ranges.
Q12: How do I handle foreign currency transactions?
Use --currency USD when creating entries. The agent fetches the BOJ reference rate for the transaction date and records the JPY equivalent automatically.