Agent Ledger

Double-entry accounting ledger for autonomous AI agents

| |

Double-entry accounting ledger CLI + MCP server for autonomous agents.

Create and manage a chart of accounts, post journal entries with full double-entry validation, and generate financial reports — all from the CLI or via an MCP server for agent integration.

Features

• Chart of Accounts — Asset, Liability, Equity, Revenue, Expense account types

• Double-Entry Validation — Every journal entry must balance (debits = credits)

• Journal Entries — Multi-line entries with descriptions, timestamps, and tags

• Financial Reports — Trial Balance, Income Statement, Balance Sheet, Cash Flow Statement

• Date-Filtered Reports — Generate reports as of a specific date or for a date range

• Multi-Currency — Accounts in different currencies with exchange rates and conversion

• Reconciliation — Mark entries as reconciled, track reconciliation status

• Entry Reversal — Reverse any posted entry with an opposing entry

• Period Close — Close accounting periods, zero out temporary accounts into retained earnings

• Account Hierarchy — Parent-child account relationships with rollup balances

• Chart of Accounts Templates — Pre-built templates for Solo, Startup, and Freelancer businesses

• CSV Import — Import accounts and journal entries from CSV files

• Audit Log — Track all ledger operations with timestamps and actor attribution

• CSV Export — Export accounts, entries, and reports to CSV files

• Cost Centers / Projects — Dimensional accounting for tracking profitability by project, department, or cost center

• Multi-Period Comparison — Side-by-side period analysis with variance and percentage change

• Settlement & Netting — Multi-party inter-agent obligation netting with dispute resolution and cryptographic settlement proofs

• Multi-Currency Settlement — Net obligations across currencies with automatic FX conversion to the batch settlement currency

• Settlement Fees — Processing, network, gas, FX spread, and commission fees with payer/payee/split allocation

• Partial Settlement — Settle net positions incrementally over time with outstanding balance tracking

• Optimization Reports — Gross vs net volume analysis, savings percentage, payment reduction metrics

• Data Persistence — JSON-based storage, portable and human-readable

• CLI — Full-featured Click CLI with rich output

• MCP Server — Model Context Protocol server for autonomous agent integration

Related MCP server: bookie

Installation

pip install agent-ledger

Quick Start

CLI

# Initialize a new ledger
agent-ledger init

# Create accounts
agent-ledger account create cash --type asset
agent-ledger account create revenue --type revenue
agent-ledger account create expenses --type expense

# Create sub-accounts (hierarchy)
agent-ledger account create bank --type asset --parent cash
agent-ledger account create petty-cash --type asset --parent cash

# Post a journal entry
agent-ledger entry post "Initial sale" cash:1000 revenue:1000

# Post with multiple lines
agent-ledger entry post "Purchase supplies" \
  expenses:500 \
  cash:500

# Reverse an entry (creates opposing entry)
agent-ledger entry reverse <entry-id> --reason "Posted in error"

# View trial balance
agent-ledger report trial-balance

# View income statement
agent-ledger report income-statement

# View balance sheet
agent-ledger report balance-sheet

# View cash flow statement
agent-ledger report cash-flow

# List accounts
agent-ledger account list

# Show account details with running balance
agent-ledger account show cash

# View account hierarchy with rollup balances
agent-ledger hierarchy tree
agent-ledger hierarchy rollup cash

# Close a period (zero out revenue/expenses into retained earnings)
agent-ledger close-period

# View audit log
agent-ledger audit list
agent-ledger audit list --action account_created --limit 10

# Export to CSV
agent-ledger export accounts --output accounts.csv
agent-ledger export entries --output entries.csv
agent-ledger export trial-balance --output tb.csv
agent-ledger export income-statement --output is.csv

# Apply a chart of accounts template
agent-ledger template list
agent-ledger template apply solo

# Import from CSV
agent-ledger import accounts accounts.csv
agent-ledger import entries entries.csv

MCP Server

agent-ledger serve

This starts an MCP server that exposes all ledger operations as tools for autonomous agents, including:

• Core: init_ledger, create_account, list_accounts, get_account, post_entry, list_entries, get_entry, delete_entry, reconcile_entry

• Reports: trial_balance, income_statement, balance_sheet, cash_flow_statement

• Multi-Currency: add_exchange_rate, list_exchange_rates

• v0.2.0: close_period, get_account_hierarchy, get_rollup_balance, validate_hierarchy, list_audit_log, export_csv, list_closed_periods

• v0.3.0: reverse_entry, apply_template, list_templates, import_accounts_csv, import_entries_csv

• v0.9.0: create_cost_center, list_cost_centers, cost_center_report, cost_center_summary, assign_entry_to_cost_center, compare_account_balances, compare_income_statements

Cost Centers / Projects

Track revenue and expenses by project, department, or cost center for profitability analysis:

# Create cost centers
agent-ledger cost-center create proj-alpha "Project Alpha" --type project
agent-ledger cost-center create dept-eng "Engineering" --type department

# Assign entries to cost centers (via MCP or programmatically)
# Then view profitability per project:
agent-ledger cost-center report proj-alpha
agent-ledger cost-center summary
agent-ledger cost-center tree

Multi-Period Comparison

Compare financial performance across time periods with variance analysis:

# Compare account balances across quarters
agent-ledger compare balances \
  -p 2024-01-01,2024-03-31,Q1 \
  -p 2024-04-01,2024-06-30,Q2

# Compare income statements across quarters
agent-ledger compare income \
  -p 2024-01-01,2024-03-31,Q1 \
  -p 2024-04-01,2024-06-30,Q2

Architecture

src/agent_ledger/
├── __init__.py        # Package init
├── models.py          # Core data models (Account, JournalEntry, etc.)
├── ledger.py          # Ledger engine (business logic + audit integration)
├── storage.py         # JSON persistence layer
├── reports.py         # Financial report generators
├── currency.py        # Multi-currency support
├── audit.py           # Audit log (entries, actions, filtering)
├── closing.py         # Period close (zero temporary accounts)
├── hierarchy.py       # Account hierarchy & rollup balances
├── export.py          # CSV export for accounts, entries, reports
├── cashflow.py       # Cash flow statement generation (indirect method)
├── templates.py      # Chart of accounts templates (solo, startup, freelancer)
├── import_csv.py     # CSV import for accounts and journal entries
├── cost_centers.py   # Cost centers / dimensional accounting
├── comparison.py     # Multi-period comparison reports
├── cli.py             # Click CLI
├── mcp_server.py      # MCP server for agent integration
└── exceptions.py      # Custom exceptions

Changelog

v1.2.0

• Multi-Currency Settlement: Items in different currencies are automatically FX-converted to the batch settlement currency before netting. The MCP server auto-wires the ledger's exchange rates as an FX converter.

• Settlement Fee Engine: 7 fee types (processing, network, gas, fx_spread, late, commission, custom) with 3 allocation strategies (payer bears, payee absorbs, 50/50 split). Fees are converted to batch currency and affect net positions.

• Partial Settlement: Settle net obligations incrementally over time. Track outstanding balances per net payment, record partial payments with references (txn hashes), and auto-finalize when fully covered.

• Optimization Reports: Detailed netting analytics — gross vs net volume, savings percentage, payment reduction ratio, per-party breakdown, fee totals, partial settlement status.

• 7 new MCP tools (105 total): add_settlement_fee, list_settlement_fees, remove_settlement_fee, record_partial_settlement, get_outstanding_balances, settle_from_partials, get_settlement_optimization_report

• 85 new tests (873 total)

v1.1.0

• Settlement & Netting Engine: Multi-party inter-agent obligation netting. Agents add obligations (who owes whom), then the engine calculates minimum settlement payments via greedy netting. Includes dispute resolution (mark items disputed, resolve them, recalculate), cryptographic settlement proofs (SHA-256), and participant position tracking.

• 9 new MCP tools (98 total): create_settlement_batch, add_settlement_item, calculate_settlement_netting, settle_batch, list_settlement_batches, get_settlement_batch, get_party_position, dispute_settlement_item, get_settlement_proof

• 80 new tests (788 total)

v1.0.0

• Alerts: Real-time alert rules with conditions (above, below, equals, changed), severity levels, and trigger tracking

• API Keys: Scoped API key management for REST API access control

• Dashboard: Self-contained HTML financial dashboard with balance sheet, income statement, trial balance, ratios, and alerts

• 81 new tests (708 total)

• Cost Centers / Projects: Dimensional accounting for tracking revenue and expenses by project, department, or cost center. Full CRUD, entry assignment, per-center financial reports, cross-center summary, and hierarchy tree

• Multi-Period Comparison: Side-by-side period comparison of account balances and income statements with variance and percentage change indicators (up/down/stable/new/gone)

• 11 new MCP tools (89 total), new CLI command groups (cost-center, compare)

• 66 new tests (580 total)

v0.2.0

• Period Close: Close accounting periods, zero out revenue/expense accounts into retained earnings

• Account Hierarchy: Parent-child account relationships with recursive rollup balances

• Audit Log: Full audit trail of all ledger operations with actor attribution and before/after snapshots

• CSV Export: Export accounts, journal entries, trial balance, income statement, balance sheet, and hierarchy to CSV

• 72 new tests (192 total)

v0.1.0

• Initial release with chart of accounts, double-entry validation, journal entries, financial reports, multi-currency, reconciliation, CLI, and MCP server

• 120 tests

License

MIT