Solobooks

Local-first billing and bookkeeping for solo consultants. Track time, generate invoices, manage expenses, reconcile bank transactions, and handle S-Corp financials (payroll, distributions, health insurance, estimated taxes) — all from a single SQLite database.

Two interfaces to the same data:

• Web UI (FastAPI + HTMX + Jinja + Alpine) for time entry, invoice generation, financial dashboards, and reconciliation.
• MCP server (49 tools) exposing the same data to Claude Code / Claude Desktop for CRUD, analytics, and ad-hoc queries.

Quickstart

git clone https://github.com/danjamk/solobooks.git
cd solobooks
uv sync
make provision            # runs migrations, walks you through setup
make run                  # http://localhost:8000

That's it. make provision prompts for your company name, consultant info, and first client. Takes about 30 seconds.

Just want to kick the tires? Use sample data instead:

make provision-sample     # loads demo data, no prompts
make run

Want to test all the features? Load the full test scenario:

make seed-test-data       # creates test client with time, invoices, expenses
make run                  # explore everything, then:
make clean-test-data      # remove test data when done

See docs/testing.md for a walkthrough.

Features

• Time tracking with per-client rates and billing periods
• Invoice generation with PDF rendering (WeasyPrint)
• Expense tracking with reimbursement workflow
• Bank transaction import (Chase CSV) with auto-categorization
• Monthly reconciliation reports
• S-Corp financials: payroll runs, shareholder distributions, health insurance payments, estimated tax payments
• Revenue analytics, P&L summaries, effective rate calculations
• Dark mode, client filtering, period selection
• Full MCP server for AI-assisted bookkeeping

Configuration

Copy .env.example to .env to override defaults. Most users don't need a .env file at all — the defaults work out of the box.

Variable	Default	Description
SB_DB_PATH	./data/billing.db	SQLite database path
SB_PDFS_DIR	./pdfs	Generated PDF directory
SB_WEB_PORT	8000	Web UI port
SB_BACKUP_DIR	./backups	Backup directory
SB_ENV	prod	Set to dev for dev/prod workflow (see below)

MCP Server

Register solobooks as an MCP server so Claude can manage your books:

Claude Code:

claude mcp add solobooks -s project -- \
  uv run --directory /path/to/solobooks \
  python -m app.mcp_server

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "solobooks": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/solobooks",
               "python", "-m", "app.mcp_server"]
    }
  }
}

Tool Categories

Category	Tools
Admin	get/update company, get/update consultant
Clients	list, detail, create, update
Projects	list, create, update
Time	list, unbilled, create, update, delete, write off, undo write-off
Expenses	list, create, update, delete
Reimbursements	get unreimbursed, record reimbursement (batch)
Invoices	summary, detail, create, submit, mark paid, void, render PDF
Analytics	dashboard stats, revenue by client, effective rate, P&L
Payroll	record payroll run, list payroll runs
S-Corp	record/list distributions, health insurance payments, estimated tax payments
Banking	import bank transactions (Chase CSV), list, categorize, create expense from transaction, get unreconciled
Reconciliation	monthly reconciliation report

Customization

See docs/branding.md for how to customize colors, fonts, invoice templates, and the app name for your business.

Make Commands

make run               # Start web UI (port 8000)
make provision         # Interactive setup (migrate + company/consultant/client)
make provision-sample  # Load sample data (no prompts)
make migrate           # Apply database migrations only
make test              # Run test suite
make lint              # Run ruff linter
make format            # Auto-format with ruff
make backup            # Timestamped DB backup
make restore           # Restore DB from a backup (interactive)
make health            # Check service, web UI, and DB health
make seed-test-data    # Load test scenario data
make clean-test-data   # Remove test scenario data

Project Layout

app/              - FastAPI app, MCP server, services, models, templates
app/services/     - Business logic (invoicing, time, clients, expenses,
                    projects, analytics, admin, payroll, scorp, banking,
                    reconciliation)
app/static/       - CSS
app/templates/    - Jinja2 templates
migrations/       - Sequenced .sql files, idempotent
scripts/          - bootstrap, migrate, test data, import
tests/            - pytest (unit, integration, smoke)
docs/             - Branding guide, testing guide
data/             - billing.db (gitignored)
backups/          - Timestamped DB backups (gitignored)
pdfs/             - Generated invoice PDFs (gitignored)

Dev/Prod Workflow (Optional)

If you want separate dev and prod instances (e.g., to test migrations before applying them to real data), create two clones:

# Dev instance
cd ~/projects/solobooks
echo "SB_ENV=dev" > .env          # port 8001, shows DEV banner

# Prod instance
cd ~/projects/solobooks-prod      # separate clone
# no .env needed — defaults to prod (port 8000)

Deploy workflow: develop and test in dev, then in prod:

cd ~/projects/solobooks-prod
git pull
make deploy              # stops service, backup, migrate, restart

Install as a persistent macOS service:

make service-install     # launchd service, starts on boot
make service-status      # check status
make service-uninstall   # stop and remove

Migrations

• Each migration is a NNNN_description.sql file under migrations/.
• Every statement must be idempotent (CREATE TABLE IF NOT EXISTS).
• Never edit an applied migration. Add a new one.
• schema_migration table tracks applied versions.

Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run make test && make lint
5. Submit a PR

License

MIT