후잉가계부

com.whooing/whooing

Source

Documentation

whooing-mcp

MCP server for Whooing (후잉) personal finance — manage transactions, view spending, balance sheets, budgets, and more.

Setup

1. Get API Credentials

Go to Whooing App Settings
Note your app_id, token, and signature
Find your section_id from the API or URL

2. Configure Environment

export WHOOING_APP_ID=3
export WHOOING_TOKEN=your_token
export WHOOING_SIGNATURE=your_signature
export WHOOING_SECTION_ID=your_section_id

Or create a .env file (see .env.example).

Usage

stdio mode (Claude Code, Claude Desktop)

npx whooing-mcp

HTTP mode (daemon)

npx whooing-mcp --http --port 8182

Claude Code config (`~/.mcp.json`)

{
  "mcpServers": {
    "whooing": {
      "command": "npx",
      "args": ["whooing-mcp"],
      "env": {
        "WHOOING_APP_ID": "3",
        "WHOOING_TOKEN": "...",
        "WHOOING_SIGNATURE": "...",
        "WHOOING_SECTION_ID": "..."
      }
    }
  }
}

Claude Desktop config

{
  "mcpServers": {
    "whooing": {
      "command": "npx",
      "args": ["whooing-mcp"],
      "env": {
        "WHOOING_APP_ID": "3",
        "WHOOING_TOKEN": "...",
        "WHOOING_SIGNATURE": "...",
        "WHOOING_SECTION_ID": "..."
      }
    }
  }
}

Tools

Tool	Description	Parameters
`whooing_pl`	Profit & loss (spending/income by category)	`start_date?`, `end_date?`, `section_id?`
`whooing_entries`	Transaction list with account names; supports client-side filters	`start_date?`, `end_date?`, `limit?`, `account_ids?`, `account_name?`, `l_account_id?`, `r_account_id?`, `min_money?`, `max_money?`, `item?`, `memo?`, `item_contains?`, `memo_contains?`, `query?`, `keywords?`, `sort_column?`, `sort_order?`, `section_id?`
`whooing_search_entries`	Search-focused transaction lookup	`start_date?`, `end_date?`, `limit?`, `account_ids?`, `account_name?`, `l_account_id?`, `r_account_id?`, `min_money?`, `max_money?`, `item?`, `memo?`, `item_contains?`, `memo_contains?`, `query?`, `keywords?`, `sort_column?`, `sort_order?`, `section_id?`
`whooing_entry_detail`	Single transaction lookup by ID	`entry_id`, `section_id?`
`whooing_duplicate_candidates`	Find likely duplicate transactions in a date range	`start_date?`, `end_date?`, `limit?`, `account_ids?`, `account_name?`, `l_account_id?`, `r_account_id?`, `min_money?`, `max_money?`, `item?`, `memo?`, `item_contains?`, `memo_contains?`, `query?`, `keywords?`, `sort_column?`, `sort_order?`, `include_memo?`, `min_group_size?`, `page_limit?`, `max_pages?`, `section_id?`
`whooing_account_activity`	Account-focused transaction summary	`start_date?`, `end_date?`, `account_id?`, `account_name?`, `limit?`, `recent_limit?`, `page_limit?`, `max_pages?`, `max_api_calls?`, `section_id?`
`whooing_balance`	Balance sheet (assets, liabilities, capital)	`start_date?`, `end_date?`, `section_id?`
`whooing_budget`	Budget status	`start_date?`, `end_date?`, `section_id?`
`whooing_accounts`	Full account list	`section_id?`
`whooing_sections`	List all sections (가계부)	(none)
`whooing_calendar`	Daily income/expense overview by month	`start_month?`, `end_month?`, `section_id?`
`whooing_monthly_summary`	Month-by-month income, expense, net amount, and transaction count	`start_month?`, `end_month?`, `section_id?`
`whooing_frequent_items`	Saved frequent transaction templates	`section_id?`
`whooing_latest_items`	Recent unique items for autocomplete (60 days)	`section_id?`
`whooing_add_entry`	Create a new transaction entry	`entry_date`, `l_account_id`, `r_account_id`, `item`, `money`, `memo?`, `section_id?`
`whooing_bulk_add_entries`	Create multiple transaction entries	`entries[]`, `section_id?`
`whooing_update_entry`	Update an existing entry	`entry_id`, `entry_date`, `l_account_id`, `r_account_id`, `item`, `money`, `memo?`, `section_id?`
`whooing_delete_entry`	Delete an entry	`entry_id`, `section_id?`

Dates use YYYYMMDD format. Default: current month (1st to today).
Calendar months use YYYYMM format. Default: current month.
whooing_entries filters are applied after fetching the date-range results from Whooing. Use a larger limit when searching busy periods.
whooing_search_entries uses Whooing's server-side filters first (item, memo, account, amount range) and paginates with the max cursor when needed.
account_name matches account titles case-insensitively, so account_name: "Game" can narrow results to a game expense category without looking up its account ID first.
When account_name matches multiple accounts, search tools split the query per account so each request can still use Whooing's server-side account filter.
min_money and max_money filter whooing_entries by amount.
query and keywords match against both item and memo; item_contains and memo_contains target one field.
item and memo pass through Whooing's raw search syntax. Use these for exact item matches, * wildcards, item detail parentheses, memo AND terms, and ! exclusions.
sort_column accepts entry_date, item, money, total, l_account_id, or r_account_id; sort_order accepts desc or asc.
Entry-list date ranges are validated before calling Whooing because entries.json supports at most one year per request.
For efficient broad searches, prefer item_contains, memo_contains, account filters, and amount filters over generic keywords; query is optimized as server-side item-or-memo search.
whooing_duplicate_candidates groups entries with the same date, amount, accounts, and item; set include_memo to make memo part of the duplicate key. Use account/item/amount filters to keep duplicate scans efficient.
whooing_account_activity accepts either account_id or account_name and summarizes only matching entries.
Search tools cap internal Whooing requests with max_api_calls to stay within API rate guidance.
whooing_account_activity also tries Whooing's account-specific aggregate APIs for daily changes, item totals, and client totals.
whooing_monthly_summary uses report_summary.json with rows_type=month for direct monthly income/expense totals.
whooing_bulk_add_entries validates account IDs for each row before creating it and reports partial failures.
section_id defaults to WHOOING_SECTION_ID env var.
Write tools resolve account types automatically from the account cache. Use whooing_accounts to look up account IDs first.

Running as a daemon (macOS launchd)

Create ~/Library/LaunchAgents/com.whooing.mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>com.whooing.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/npx</string>
        <string>whooing-mcp</string>
        <string>--http</string>
        <string>--port</string>
        <string>8182</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>WHOOING_APP_ID</key><string>3</string>
        <key>WHOOING_TOKEN</key><string>YOUR_TOKEN</string>
        <key>WHOOING_SIGNATURE</key><string>YOUR_SIGNATURE</string>
        <key>WHOOING_SECTION_ID</key><string>YOUR_SECTION_ID</string>
        <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    </dict>
    <key>KeepAlive</key><true/>
    <key>RunAtLoad</key><true/>
    <key>StandardOutPath</key><string>/tmp/whooing-mcp.log</string>
    <key>StandardErrorPath</key><string>/tmp/whooing-mcp.err</string>
</dict>
</plist>

chmod 600 ~/Library/LaunchAgents/com.whooing.mcp.plist
launchctl load ~/Library/LaunchAgents/com.whooing.mcp.plist

Development

git clone https://github.com/jmjeong/whooing-mcp.git
cd whooing-mcp
npm install
npm run build
node dist/cli.js

License

MIT