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

# 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

Create a project at supabase.com
Go to SQL Editor
Copy-paste the contents of schema.sql
Run it — this creates all tables, indexes, and constraints
Go to Settings → Database → Connection string
Copy the URI connection string (starts with postgresql://)
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:

hermes mcp add finance --command /path/to/finance-mcp

Or manually add to ~/.hermes/config.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

# 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

MCP Servers