quidclaw 0.1.0

MCP-based personal finance AI Agent powered by Beancount

QuidClaw

Your AI-powered Personal CFO.

Local-first. Privacy by design. Your data never leaves your machine.

QuidClaw is an open-source MCP server that gives AI assistants the ability to manage your personal finances using Beancount double-entry accounting. Connect it to Claude, ChatGPT, or any MCP-compatible client — and you have a Personal CFO that tracks every dollar, generates reports, and keeps your books clean.

"Lunch was $12, paid with Apple Pay" → AI calls QuidClaw → proper double-entry transaction recorded in your local ledger.

Chinese / 中文文档

Why QuidClaw

• Privacy first — All data stored locally as plain text. No servers, no cloud, no telemetry. Nothing ever leaves your machine.
• You own your data — Standard Beancount .bean files you can read, edit, and version control. No vendor lock-in, no proprietary formats.
• AI-powered, not AI-dependent — QuidClaw is just tools. The intelligence comes from your AI client. Switch AI providers anytime.

How It Works

You ──(natural language)──→ AI Client ──(MCP)──→ QuidClaw ──→ Beancount
                                                                  ↓
                                                          ~/.quidclaw/*.bean

• You talk naturally to your AI assistant
• AI understands your intent and decides which tools to call
• QuidClaw provides 10 MCP tools that read/write Beancount ledger files
• Data is stored locally as plain text — you own it completely

QuidClaw doesn't run any AI model. It's a bridge between your AI client and the Beancount accounting engine.

Features

• Record transactions via natural language
• Multi-currency support (USD, EUR, CNY, etc.)
• Balance queries and reconciliation
• Financial reports (income statement, balance sheet)
• Flexible BQL (Beancount Query Language) queries
• Price tracking for stocks, crypto, and forex
• Interactive account setup for new users

Prerequisites

Requirement	Description
Python 3.10+	Check with python3 --version.
An MCP client	Any app that supports the Model Context Protocol. See setup options below.

Quick Install

The fastest way to install QuidClaw into all your MCP clients at once:

npx add-mcp --uvx quidclaw -a claude-code -a claude-desktop -a cursor -a codex

This installs QuidClaw via add-mcp and configures it for all specified clients in one command. Remove any -a <client> you don't use, or add others like -a zed, -a vscode, -a windsurf.

That's it. Restart your client and start chatting.

Manual Setup

If you prefer to configure a specific client manually, or if add-mcp doesn't support your client yet:

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "quidclaw": {
      "command": "uvx",
      "args": ["quidclaw"]
    }
  }
}

Claude Code

claude mcp add quidclaw -- uvx quidclaw

Cursor / Windsurf

Add to your MCP config (Settings → MCP Servers):

{
  "mcpServers": {
    "quidclaw": {
      "command": "uvx",
      "args": ["quidclaw"]
    }
  }
}

Codex

Add to ~/.codex/config.toml (or run codex mcp add):

[mcp_servers.quidclaw]
command = "uvx"
args = ["quidclaw"]
type = "stdio"

VS Code (Copilot)

Add to your .vscode/mcp.json:

{
  "servers": {
    "quidclaw": {
      "command": "uvx",
      "args": ["quidclaw"]
    }
  }
}

Other MCP clients

QuidClaw is a standard MCP server using stdio transport. Configure your client to run:

uvx quidclaw

Install from Source (for development)

git clone https://github.com/thorb/quidclaw.git
cd quidclaw
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Usage

Once connected, just talk to your AI naturally:

You: Help me set up my ledger

AI: (calls init_ledger) Created 20 default accounts. What bank accounts do you have?

You: Chase checking and Amex credit card

AI: (calls add_account twice) Done. Want to set initial balances?

You: Chase has $5,200

AI: (calls add_transaction) Recorded opening balance.

You: Lunch was $12, paid with Apple Pay

AI: (calls add_transaction) Recorded: Expenses:Food $12.00 from Assets:ApplePay

Data Storage

All data is stored locally as plain text Beancount .bean files:

~/.quidclaw/
├── main.bean          # includes all other files
├── accounts.bean      # account definitions
├── prices.bean        # price directives
└── 2026/
    ├── 2026-01.bean   # January transactions
    ├── 2026-02.bean   # February transactions
    └── ...

Default directory: ~/.quidclaw/. To customize:

export QUIDCLAW_DATA_DIR="/path/to/your/ledger"

MCP Tools

QuidClaw exposes 10 tools to AI clients:

Tool	Description
init_ledger	Initialize ledger with default or custom accounts
add_account	Open a new account
close_account	Close an account
list_accounts	List accounts, optionally filtered by type
add_transaction	Record a transaction
get_balance	Query account balances
balance_check	Verify balance for reconciliation
query	Execute arbitrary BQL queries
report	Generate income statement or balance sheet
fetch_prices	Fetch commodity prices

See MCP Tools Reference for full parameter details.

Development

See Install from Source above, then:

pytest

See Architecture for design details.

License

This project is licensed under the GNU General Public License v2.0, the same license used by Beancount.