money-forward-mcp-community

Unofficial, community-maintained stdio MCP server and TypeScript client for Money Forward ME.

It reads Money Forward ME's authenticated web pages with a user-provided Cookie header and exposes portfolio, liabilities, linked accounts, cashflow, household-book summaries, and manual accounts as structured MCP tools.

[!WARNING] This project is unofficial and is not affiliated with Money Forward, Inc. or Money Forward Home, Inc. Internal endpoints and HTML can change without notice. Treat Cookies and returned financial data as secrets. Never put them in GitHub issues, logs, npm packages, or public prompts. Review the latest Money Forward terms before use.

Capabilities

• Portfolio total, asset-class allocation, and individual holdings
• Liability total, class allocation, loans, and card balances
• Flat account view across banks, securities, points, cards, and loans
• Monthly cashflow rows with direction and calculation-target filters
• Monthly income, expense, net balance, and category summaries
• Custom/manual account and asset lookup
• Browser login, trusted Cookie import, authentication checks, and rolling Cookie refresh

Data tools never modify financial records. Month-specific cashflow reads update Money Forward's selected-month session state and may persist a rotated Cookie.

Quick start

Local / desktop

npx money-forward-mcp-community auth
npx money-forward-mcp-community auth --status

Complete login and multi-factor authentication in the browser. The Cookie is stored at:

~/.config/money-forward-mcp-community/config.json

Example MCP client configuration:

{
  "mcpServers": {
    "money-forward-me": {
      "command": "npx",
      "args": ["-y", "money-forward-mcp-community"]
    }
  }
}

Server / Hermes / CI

Do not automate email/password login on a remote server. Export a Cookie from a trusted authenticated browser and supply it through a secret manager or a protected config file.

MONEY_FORWARD_COOKIE='your Cookie header' \
  npx -y money-forward-mcp-community

Or mount a config file:

{
  "cookie": "your Cookie header",
  "updatedAt": "2026-07-20T00:00:00.000Z"
}

MONEY_FORWARD_MCP_COMMUNITY_CONFIG=/run/secrets/money-forward/config.json \
  npx -y money-forward-mcp-community

Tool selection for agents

Use compact summary tools before requesting large detail payloads.

User intent	Preferred tool	Notes
Net worth or balances by bank/card/account	money_forward_get_account	Flat signed balances; assets positive, liabilities negative
Total assets or allocation	money_forward_get_portfolio_summary	Compact; includes zero-balance asset classes
Individual holdings or valuation details	money_forward_get_portfolio_details	Larger response; grouped by asset class
Total debt or debt allocation	money_forward_get_liability_summary	Positive amounts owed
Individual loans or card balances	money_forward_get_liability_details	Positive amounts owed
Monthly income, spending, net, or category totals	money_forward_get_cashflow_summary	Prefer an explicit month
Individual monthly cashflow rows	money_forward_get_cashflow_details	Supports direction and calculation-target filters
Custom/manual accounts only	money_forward_list_manual_accounts	Not linked banks, cards, or securities
Assets inside one manual account	money_forward_list_manual_assets	Requires id from the previous tool

Recommended agent workflow

1. If a data tool reports missing or expired authentication, call money_forward_auth_status, then money_forward_auth_check.
2. For monthly analysis, call money_forward_get_cashflow_summary first.
3. Call money_forward_get_cashflow_details only when individual transactions are necessary.
4. For net worth by account, call money_forward_get_account and sum its signed balance values.
5. For asset composition, use Portfolio tools rather than reconstructing allocation from account rows.

Structured output

Successful tools return both human-readable JSON text and MCP structured output. Programmatic consumers should read:

response.structuredContent.result;

Each tool declares an MCP outputSchema, allowing compatible agents to inspect the response contract before calling it.

Errors set isError: true and return a stable object in structuredContent.error:

{
  "code": "auth_required",
  "message": "Money Forward ME authentication is not configured.",
  "retryable": false,
  "suggestedTools": ["money_forward_auth_login", "money_forward_set_cookie"]
}

Defined error categories include authentication requirements/expiry, upstream timeouts or HTTP errors, and page-format changes.

Account model

money_forward_get_account returns a flat array. There is no institution-specific nested subAccounts model.

type MoneyForwardAccountEntry = {
  accountId: string | null;
  institution: string;
  name: string;
  kind: "asset" | "liability";
  category: string | null;
  balance: number;
  currency: "JPY";
  source: "account_detail" | "portfolio" | "liability" | "account_summary";
  registeredAt: string | null;
  lastFetchedAt: string | null;
  status: string | null;
};

Example:

[
  {
    "institution": "Example Bank",
    "name": "Savings",
    "kind": "asset",
    "category": null,
    "balance": 1500000,
    "currency": "JPY",
    "source": "account_detail"
  },
  {
    "institution": "Example Bank",
    "name": "Home loan",
    "kind": "liability",
    "category": "Mortgage",
    "balance": -12000000,
    "currency": "JPY",
    "source": "liability"
  }
]

Account sign convention

• kind: "asset": balance is zero or positive
• kind: "liability": balance is zero or negative
• Sum all balance values to obtain net value

source preserves the Money Forward page used for the row:

Source	Meaning
account_detail	A sub-account from a linked institution's detail page
portfolio	A Portfolio holding such as points or stored value
liability	A Liability row such as a loan or card balance
account_summary	Institution total used when no lower-level row is available

Matching across pages is generic and based on Money Forward's institution labels. No bank or card name is hard-coded. A source label is retained so agents can explain provenance and avoid treating fallback totals as detailed holdings. Portfolio or liability rows with an institution label that does not match a registered account are retained with accountId: null rather than silently discarded.

Cashflow

Both cashflow tools accept an optional month:

{ "month": "2026-06" }

Use explicit YYYY-MM whenever reproducibility matters. If omitted, Money Forward's currently displayed month is used. Selecting a month performs Money Forward's session-level month switch before reading; it does not edit transactions or household-book records.

money_forward_get_cashflow_details also accepts:

{
  "month": "2026-06",
  "direction": "expense",
  "calculationTargetOnly": true
}

• direction: all, income, or expense
• calculationTargetOnly: exclude rows Money Forward does not use in household-book calculations
• Transaction amount: income positive, expense negative
• Summary income and expense: both positive totals
• Summary balance: income minus expense

Portfolio and liabilities

Portfolio and Liability deliberately keep Money Forward's original concepts separate:

• Portfolio summary/details describe assets and holdings.
• Liability summary/details describe positive amounts owed.
• Account entries normalize liabilities to negative signed balances for net-value calculations.

Do not add Portfolio and account asset totals together: they are different views of overlapping financial data.

Authentication tools

Tool	Behavior
money_forward_auth_status	Checks local configuration only; no network request
money_forward_auth_check	Verifies the configured Cookie against Money Forward
money_forward_auth_login	Opens a Playwright browser and stores Cookies locally
money_forward_set_cookie	Verifies and stores a trusted Cookie header
money_forward_clear_cookie	Deletes the config-file Cookie; does not change environment variables

Authentication priority:

1. MONEY_FORWARD_COOKIE
2. MF_ME_COOKIE (compatibility)
3. MONEY_FORWARD_MCP_COMMUNITY_CONFIG
4. ~/.config/money-forward-mcp-community/config.json

CLI:

money-forward-mcp-community auth
money-forward-mcp-community auth --status
money-forward-mcp-community auth --clear
money-forward-mcp-community set-cookie '<COOKIE_HEADER>'
money-forward-mcp-community serve

If Chromium is not installed:

npx -p playwright playwright install chromium

Cookie refresh

Money Forward may rotate session Cookies on authenticated responses.

• Config-file Cookies are updated atomically after a successful authenticated response.
• The temporary file and final config use mode 0600.
• Environment-variable Cookies are never persisted to disk.
• Cookie values, previews, and local config paths are not returned by MCP authentication tools.

A Cookie can still be invalidated server-side by logout, password changes, or security policy. Use money_forward_auth_check when data access fails.

TypeScript API

import { MoneyForwardClient, readCookie } from "money-forward-mcp-community";

const client = new MoneyForwardClient({ cookie: await readCookie() });

const accounts = await client.getAccounts();
const JuneSummary = await client.getHouseholdBookSummary("2026-06");
const manualAccounts = await client.listManualAccounts();

Environment

Variable	Default	Description
MONEY_FORWARD_COOKIE	none	Money Forward Cookie header
MF_ME_COOKIE	none	Compatibility Cookie environment variable
MONEY_FORWARD_MCP_COMMUNITY_CONFIG	default config path	Config JSON path
MONEY_FORWARD_REQUEST_TIMEOUT_MS	15000	Request timeout, 100–120000 ms
MONEY_FORWARD_MCP_COMMUNITY_HEADLESS	false	Browser-login headless mode

Security and limitations

• Cookies provide access to financial data. Treat them like passwords.
• The server uses unofficial HTML and internal web behavior, not a supported public API.
• Money Forward can change pages, labels, or session behavior without notice.
• lastFetchedAt is the display label provided by Money Forward and may omit the year.
• Foreign-currency balances can be returned as Money Forward's JPY valuation.
• Only use accounts you own or are authorized to manage.
• Review the data-retention and model-training settings of the MCP host and AI client.

Development

npm install
npm run format
npm run check
npm test
npm run lint
npm run build
npm pack --dry-run

Release

Conventional Commits on main are processed by GitHub Actions and semantic-release to create GitHub and npm releases. Configure new-village/money-forward-mcp-community and .github/workflows/release.yml as npm Trusted Publishers. NPM_TOKEN is not required.

License

MIT