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.

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.

Related MCP server: KSEI MCP

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.

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:

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

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

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