GuGuFin GuGuFin 財務整理筆記 · 第四篇
GuGuFin macOS MCP 設定教學：用 AI Agent 查帳、對帳與記帳
了解 GuGuFin macOS MCP Server 的本機 HTTP 連線、Bearer Token、帳本匯入與寫入確認。讓支援 MCP 的 AI Agent 查詢個人財務並協助信用卡對帳。
GuGuFin macOS 版提供本機 MCP Server，讓支援 MCP 的 AI Agent 透過帳務工具查詢收支、資產負債與投資紀錄，並準備記帳提議。你可以先查看 MCP 功能與使用情境，再依這篇教學建立連線。
開始前需要什麼？
- 已安裝的 GuGuFin macOS 選單列 App，以及要使用的帳本備份。
- 能連接本機 Streamable HTTP MCP、設定 Bearer Token 的客戶端。
- 備份密碼（若備份已加密），以及完成設定與確認帳務的時間。
Codex、Claude Desktop、Cursor 等客戶端的設定格式與傳輸支援可能不同。請以客戶端當前文件與 GuGuFin 產生的端點為準；若客戶端不能直接連接本機 HTTP MCP，可能需要橋接器。
1. 載入帳本並啟動 MCP
- 開啟 GuGuFin macOS 版，從選單列匯入 GuGuFin 備份。
- 輸入備份密碼並解鎖工作區，確認載入的是你想使用的帳本。
- 啟動 MCP Server，再複製 App 產生的 MCP JSON 設定。
2. 設定端點與驗證
以下是通用設定形狀，不是 Claude Desktop 或所有客戶端都能直接使用的設定檔。實際 URL、port 與 token 應從執行中的 GuGuFin 複製，不要照抄佔位值。
{
"mcpServers": {
"gugufin": {
"type": "http",
"url": "http://127.0.0.1:<APP_PORT>/mcp",
"headers": {
"Authorization": "Bearer <APP_GENERATED_TOKEN>"
}
}
}
}
將端點與 Authorization 標頭填入客戶端對應的 MCP 設定。Token 是連線憑證，不要貼到公開文章、issue、影片或共用文件。GuGuFin 端點限制在本機 loopback；遠端雲端連接器不能把你 Mac 的 127.0.0.1 當作它自己的本機來連接。
3. 先驗證查詢，再嘗試寫入
先要求 Agent「列出可用的帳本」，確認帳本名稱、資料來源和連線狀態。成功後再指定帳本、日期範圍與幣別，例如：
整理指定帳本上個月的分類支出，列出總額與前三大類別，標明使用的期間與幣別。
Agent 可以呼叫 get_category_breakdown、get_cashflow 或 get_financial_report 等工具。實際結果依帳本內容、更新時間與客戶端能力而異；資料不足時應補問，不應自行猜出交易或金額。
信用卡對帳的使用方式
先選定信用卡與帳單週期，將外部帳單明細提供給 Agent 整理。透過 preview_credit_card_reconciliation_match 預覽配對候選，再檢查未配對、需要確認或可能延後入帳的項目。
配對建議不代表銀行已確認的結果。要更新對帳狀態時，先產生 propose_credit_card_reconciliation 提議，檢查完整內容，再明確同意確認。請遮蔽與這次對帳無關的個人資料。
寫入提議與確認
收入、支出、投資或固定支出等支援的變更，先由工具產生提議。Agent 應展示帳本、帳戶、金額、日期與受影響內容；你明確確認後，才呼叫 confirm_write。
這不是讓 Agent 自由執行 SQL。缺少必要資訊時應先補齊；跨帳本轉帳等工具也有各自支援的幣別、帳本和操作限制。修改後請檢查目前工作區；若要透過備份帶回手機，使用選單列的匯出備份功能。
本地 MCP 不等於資料完全不離開裝置
MCP Server 在本機運行，但工具結果會交給你選擇的 Agent。使用雲端 AI 時，結果可能送到該 AI 服務商處理，資料留存與模型訓練政策依服務與帳號設定而定。開啟 iCloud 的帳本也會透過 Apple 同步。
查詢使用的是目前載入的帳本資料，不能把備份或歷史行情當成即時銀行餘額與即時股價。先確認更新時間，再解讀財務結果。
連不上時先檢查什麼？
- 服務未啟動或帳本未解鎖：回到選單列確認工作區與 MCP 狀態。
- 端點或 token 過期：重新複製 App 設定；更換 token 後，客戶端也要更新。
- 客戶端不支援 HTTP／驗證標頭：查看客戶端的 MCP 文件與橋接方式。
- 查不到預期紀錄：確認帳本、日期、信用卡週期，以及備份或同步資料的更新時間。