GuGuFin macOS MCP Setup: Connect an AI Agent to Your Finances

GuGuFin for macOS provides a local MCP Server. An MCP-compatible agent can query income, expenses, assets, liabilities and investment records, and prepare bookkeeping proposals. Explore the MCP features and use cases before connecting.

Requirements

• The GuGuFin macOS menu bar app and the ledger backup you want to use.
• An MCP client supporting local Streamable HTTP and Bearer Token authentication.
• Your backup password if encrypted, and time to review setup and accounting results.

Configuration formats and transport support vary across Codex, Claude Desktop, Cursor and other clients. Use current client documentation and the endpoint generated by GuGuFin. A client without direct local HTTP support may require a bridge.

1. Load a ledger and start MCP

1. Open GuGuFin on Mac and import a GuGuFin backup from the menu bar.
2. Enter the backup password, unlock the workspace and check the loaded ledger.
3. Start MCP Server and copy the MCP JSON generated by the app.

2. Configure the endpoint and authentication

This is a generic configuration shape, not a drop-in Claude Desktop configuration or a universal client format. Copy the actual URL, port and token from the running app rather than using these placeholders.

{
  "mcpServers": {
    "gugufin": {
      "type": "http",
      "url": "http://127.0.0.1:<APP_PORT>/mcp",
      "headers": {
        "Authorization": "Bearer <APP_GENERATED_TOKEN>"
      }
    }
  }
}

Map the endpoint and Authorization header to your client’s MCP settings. The token is a credential: keep it out of public issues, videos and shared documents. The endpoint is loopback-only. A remote cloud connector cannot reach your Mac by connecting to its own 127.0.0.1.

3. Verify a query before trying writes

Ask the agent to list available ledgers. Check ledger names, data sources and connection status. Then specify a ledger, period and currency:

Summarize last month’s spending categories in the selected ledger. Show the total and top three categories, and state the period and currency.

Tools include get_category_breakdown, get_cashflow and get_financial_report. Results depend on ledger contents, update time and client capabilities. Missing facts should lead to clarification, not invented transactions or amounts.

Credit card reconciliation

Choose a credit card and billing cycle, then provide external statement rows for your agent to structure. Use preview_credit_card_reconciliation_match to inspect candidate matches, unmatched rows and potentially deferred transactions.

Suggestions are not bank-confirmed matches. To update reconciliation status, first prepare a propose_credit_card_reconciliation proposal, review the complete details and explicitly approve confirmation. Redact personal information unrelated to the task.

Write proposals and confirmation

Supported income, expense, investment and recurring-expense changes start as proposals. Your agent should show the ledger, accounts, amounts, dates and affected records, and call confirm_write only after explicit approval.

This does not expose arbitrary SQL. Supply required facts and respect each tool’s scope, including currency and ledger restrictions for cross-book transfers. Check the workspace after changes. To move changes back to a phone through a backup, use the menu bar’s backup export action.

Local MCP does not mean all AI processing is offline

The server runs locally, but tool results are handed to your selected agent. A cloud AI provider may process them on its servers; retention and training policies depend on the service and account settings. Ledgers with iCloud enabled also sync through Apple.

Queries use the currently loaded ledger. Backup snapshots and stored prices are not live bank balances or guaranteed real-time market data. Check timestamps before interpreting results.

Connection troubleshooting

• Server stopped or workspace locked: check both states in the menu bar.
• Outdated endpoint or token: copy the configuration again; update the client after token rotation.
• Unsupported transport or headers: check client documentation and bridge options.
• Missing records: verify the ledger, period, billing cycle and backup or sync timestamp.

Explore GuGuFin MCP features and FAQs · Get GuGuFin for macOS