Jarv

🚀 Jarvis — Personal Finance MCP Server + Agent

A Model Context Protocol (MCP) server for personal finance tracking, backed by Notion databases. It includes an LLM-powered agent (Gemini) that parses natural language into structured tool calls.

⚠️ Important Note

This project is tightly coupled to a specific Notion workspace:
Jarvis Notion Site

The database schemas, relations, and formulas are configured within Notion itself. To use this project, duplicate the Notion template to proceed.

🚀 Quick Start

This project is a Model Context Protocol (MCP) server for personal finance tracking, relying on Notion databases. It also comes with an LLM-powered agent (Gemini) that can convert natural language into structured tool calls.

✨ Features

• Unified add_transaction: Handles expenses, income, and payments in one tool
• Account-level balances: Credit card outstanding computed from total expenses minus total payments, not from individual expense clearing
• Auto-clear payments: When adding a payment, automatically marks matching uncleared expenses as cleared (updates funding account reserves)
• Category validation: Unknown categories are coerced to "other"
• Category caching: Fetched from Notion with 5-minute TTL
• LLM-agnostic design: Agent layer can swap Gemini for any LLM
• Batch operations: Efficient bulk transaction and category updates

📦 Installation

1. Prerequisites

• Node.js 18+
• Notion account with API integration
• Gemini API key

2. Notion Database Setup

Create 6 databases in Notion with these schemas:

3. Environment Variables

Copy env.example to .env and fill in:

# Notion
NOTION_API_KEY=secret_xxx
EXPENSES_DB_ID=xxx
INCOME_DB_ID=xxx
PAYMENTS_DB_ID=xxx
ACCOUNTS_DB_ID=xxx
CATEGORIES_DB_ID=xxx
BUDGET_RULES_DB_ID=xxx

# Gemini (for Agent)
GEMINI_API_KEY=xxx

# Optional: custom ports
PORT=3000           # MCP server
AGENT_PORT=4000     # Agent server
MCP_BASE_URL=http://localhost:3000

4. Install & Run

npm install

# Terminal 1: MCP Server
npm run mcp

# Terminal 2: Agent Server
npm run agent

💻 Usage Examples

Basic Usage

MCP Server (localhost:3000)

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "add_transaction",
    "arguments": {
      "amount": 12.34,
      "transaction_type": "expense",
      "account": "sapphire",
      "funding_account": "checkings",
      "category": "groceries",
      "date": "2026-01-10",
      "note": "Trader Joes"
    }
  }
}

Agent Server (localhost:4000)

POST /chat
Content-Type: application/json

{
  "message": "spent $12.34 on groceries at Trader Joes yesterday"
}

Response:

{
  "reply": "added expense of $12.34 to sapphire (category: groceries).",
  "meta": {
    "action": { "action": "add_transaction", "args": {...} },
    "mcp": {...}
  }
}

📚 Documentation

MCP Tools Reference

Transactions

Categories

Budgets

API Endpoints

MCP Server (localhost:3000)

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "add_transaction",
    "arguments": {
      "amount": 12.34,
      "transaction_type": "expense",
      "account": "sapphire",
      "funding_account": "checkings",
      "category": "groceries",
      "date": "2026-01-10",
      "note": "Trader Joes"
    }
  }
}

Agent Server (localhost:4000)

POST /chat
Content-Type: application/json

{
  "message": "spent $12.34 on groceries at Trader Joes yesterday"
}

Response:

{
  "reply": "added expense of $12.34 to sapphire (category: groceries).",
  "meta": {
    "action": { "action": "add_transaction", "args": {...} },
    "mcp": {...}
  }
}

Valid Accounts

Balance Model

Account balances are computed with account-level math via Notion formulas, not by summing individual expense statuses.

ledger_balance formula

if(account_type == "credit",
  total_expenses - total_payments_in,
  starting_balance + total_income - total_payments_out - total_expenses
)

• Credit cards: Outstanding = charges minus payments received. A payment immediately reduces the balance by its full amount, regardless of whether individual expenses are cleared.
• Debit/savings accounts: Balance = starting balance + income - payments out - direct expenses.

reserved_for_cc (rollup)

Sums owed_amount from credit card expenses where funding_account = this account. Shows funding accounts (e.g., checkings) how much is earmarked for unpaid credit card expenses.

available_to_spend (formula)

ledger_balance - reserved_for_cc

Expense clearing (reconciliation)

When a payment is created via the API, payments.ts auto-clears matching expenses (oldest first). This sets paid_amount on each expense, which reduces owed_amount (formula: amount - paid_amount), which in turn reduces reserved_for_cc on the funding account. Clearing is required for funding account accuracy but does not affect the credit card's ledger_balance.

Example Natural Language Inputs (Agent)

Development

# Type check
npm run typecheck

# Run MCP server (hot reload)
npm run mcp

# Run Agent server (hot reload)
npm run agent

📄 License

MIT