finance-mcp

# Finance MCP A **Go MCP (Model Context Protocol) server** for personal finance tracking, backed by PostgreSQL via Supabase. Designed to be used through AI agents like Hermes Agent. ## Tech Stack - **Go 1.24** — single binary, zero external runtime dependencies - **PostgreSQL (Supabase)** — free tier, 500MB database - **MCP Protocol** — JSON-RPC 2.0 over stdio, `tools/list` + `tools/call` - **lib/pq** — native PostgreSQL driver ## Features - 15 MCP tools covering wallets, categories, transactions, budgets, and configuration - UUID-based primary keys across all entities - Full budget tracking with actual spending comparison - Configurable monthly reset day - Per-wallet and per-category breakdowns - Comprehensive `get_docs` endpoint for AI agent onboarding ## Quick Start ```bash # Clone git clone <repo-url> finance cd finance # Build go build -o finance-mcp ./cmd/finance-mcp/ # Run tests go test ./cmd/finance-mcp/... # Run (requires DATABASE_URL) export DATABASE_URL="postgresql://..." ./finance-mcp ``` ## Supabase Setup 1. Create a project at [supabase.com](https://supabase.com) 2. Go to **SQL Editor** 3. Copy-paste the contents of `schema.sql` 4. Run it — this creates all tables, indexes, and constraints 5. Go to **Settings → Database → Connection string** 6. Copy the URI connection string (starts with `postgresql://`) 7. Set it as `DATABASE_URL` environment variable ## MCP Tools | Tool | Description | |------|-------------| | `get_docs` | Get comprehensive usage documentation for all tools | | `add_wallet` | Create a wallet (bank, ewallet, cash) | | `list_wallets` | List all wallets | | `delete_wallet` | Delete a wallet by UUID | | `add_category` | Create an income or expense category | | `list_categories` | List categories, optionally filtered by type | | `add_transaction` | Record a transaction (income/expense) | | `get_recent_transactions` | List recent transactions with wallet and category names | | `delete_transaction` | Delete a transaction by UUID | | `get_balance` | Get total income, expense, and balance | | `get_monthly_summary` | Monthly totals + budget breakdown + per-wallet totals | | `set_budget` | Create or update a monthly category budget | | `get_budgets` | List monthly budgets with actual spending and remaining | | `get_config` | Get all config key-value pairs | | `set_reset_day` | Set monthly reset day (1-31) | ## Hermes Agent Config Install the MCP server: ```bash hermes mcp add finance --command /path/to/finance-mcp ``` Or manually add to `~/.hermes/config.yaml`: ```yaml mcp: servers: finance: command: /path/to/finance-mcp env: DATABASE_URL: "postgresql://..." ``` Then `/reset` or restart Hermes. The agent will auto-discover all 15 tools. ## Example Usage (via AI Agent) ``` User: catat pengeluaran 50rb buat makan siang pake GoPay Agent calls: 1. list_wallets → finds GoPay wallet 2. list_categories → finds "Makan" category 3. add_transaction(wallet_id="...", category_id="...", amount=50000, type="expense", note="makan siang") User: berapa budget gue bulan ini? Agent calls: 1. get_monthly_summary(month="2026-06") 2. get_budgets(month="2026-06") Agent responds: total expense 2.4jt dari budget 3jt, remaining 600rb. Kategori Makan overspent 1.2jt/1jt (RED), Transport 300rb/500rb ok. ``` ## Project Structure ``` finance/ ├── cmd/ │ └── finance-mcp/ │ ├── main.go # MCP server implementation (787+ lines) │ └── main_test.go # Comprehensive tests (550+ lines) ├── schema.sql # Database schema for Supabase ├── finance-mcp # Compiled binary ├── go.mod ├── go.sum ├── .env.example └── README.md ``` ## Development ```bash # Build go build -o finance-mcp ./cmd/finance-mcp/ # Run all tests go test ./cmd/finance-mcp/... # Run tests with verbose output go test -v ./cmd/finance-mcp/... # Vet checks go vet ./... # Smoke test the binary (will fail without DATABASE_URL — that's expected) echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./finance-mcp ``` ## Data Model ``` wallets → id, name, type (bank|ewallet|cash), created_at categories → id, name, type (income|expense), created_at transactions → id, wallet_id (FK), category_id (FK), amount, type, note, transaction_date, created_at budgets → id, category_id (FK), month, amount, created_at, updated_at config → key (PK), value, updated_at ``` All integer amounts are in rupiah. All IDs are UUID v4. ## Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `DATABASE_URL` | Yes | PostgreSQL connection string (Supabase) | | `SUPABASE_URL` | No | Fallback if DATABASE_URL is not set | ## License MIT