# Uncommon Cash

> AI-powered personal finance app. Track transactions, manage budgets, analyze spending, and plan finances. A modern alternative to YNAB and Monarch Money.

Uncommon Cash (uncommoncash.com) is a full-stack personal finance SaaS application. It supports transaction tracking, budget management, category-based spending analysis, net worth tracking, automation rules, and AI-powered financial planning.

## Agent Access

Uncommon Cash exposes an MCP (Model Context Protocol) server at `https://uncommoncash.com/api/mcp` that allows authorized AI agents to read and manage financial data.

**Authentication:** Bearer token required. Generate a token at https://uncommoncash.com/settings (Settings > Agent Access). Tokens are scoped — request only the permissions you need.

**MCP Server:** https://uncommoncash.com/api/mcp
**Claude Code config:**
```json
{
  "mcpServers": {
    "uncommoncash": {
      "type": "http",
      "url": "https://uncommoncash.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

## Available Tools

See full tool list with schemas: https://uncommoncash.com/.well-known/agent-skills/index.json

**Query tools (read:* scopes):**
- `get_transactions` — query transactions by date, category, amount, description
- `get_uncategorized_transactions` — transactions without a category
- `search_transactions` — full-text search across transaction descriptions
- `get_budget_vs_actual` — budget vs. actual spend by category for a month
- `get_spending_summary` — monthly spending breakdown by category
- `compare_months` — month-over-month spending comparison
- `get_net_worth` — current net worth and historical snapshots
- `get_categories` — full category hierarchy (income / expense / savings)
- `get_accounts` — linked accounts and balances
- `get_automation_rules` — pattern-matching categorization rules
- `get_financial_profile` — income, assets, goals, risk profile

**Action tools (write:* scopes):**
- `categorize_transaction` — assign a category to a transaction
- `bulk_categorize_transactions` — categorize multiple transactions at once
- `update_transaction_description` — set a human-readable description
- `create_automation_rule` — create a pattern-matching rule (optionally apply retroactively)
- `update_budget` — set or update a category budget amount
- `add_budget_note` — annotate a budget decision

**Analysis tools (read:* scopes):**
- `suggest_automation_rules` — suggest rules based on uncategorized transaction patterns
- `analyze_spending_patterns` — identify trends, top vendors, anomalies

## Key Concepts

**Categories:** Hierarchical. Each has a type: `income`, `expense`, or `savings`. Categories can have parent/child relationships. Budgets are set per category per year.

**Transactions:** Imported from bank connections (SimpleFin) or CSV. Each has a date, amount, description, and optional human_description. Transactions are assigned a category via manual selection, automation rules, or AI.

**Automation Rules:** Pattern-matching rules that auto-categorize transactions. Patterns match on description (contains, equals, starts_with, ends_with). Rules can have multiple conditions.

**Sources:** Data sources (bank connections or CSV uploads) that transactions are imported from.

**Budgets:** Set per category, per year. Budget type is `monthly` (monthly limit) or `yearly` (annual limit). Budget vs. actual tracking is the core planning feature.

**Net Worth:** Monthly snapshots of assets and liabilities. Asset types: cash, investments, property, real_estate, vehicle, other. Liability types: credit_card, loan, mortgage, other.

## API Reference

REST API catalog: https://uncommoncash.com/.well-known/api-catalog.json

The mobile REST API (`/api/v1/mobile/*`) is available for simpler integrations:
- `GET /api/v1/mobile/transactions` — list transactions
- `GET /api/v1/mobile/categories` — list categories
- `GET /api/v1/mobile/accounts/balances` — account balances
- `GET /api/v1/mobile/spend/by-category` — spending by category
- `POST /api/v1/mobile/transactions/categorize` — categorize a transaction

All endpoints require `Authorization: Bearer <token>`.