ledger-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ledger-mcp Cross-examine my rent ledger for any discrepancies with my lease."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
LedgerMCP
Keep an eye on your rent ledger — and cross-examine it against your lease — through your AI assistant.
LedgerMCP is a Model Context Protocol server built for renters. Import your property/rent-portal ledger (CSV, TSV, Excel) and your lease (PDF), and LedgerMCP gives an AI assistant a set of deterministic tools to answer questions like:
"Am I being charged the right rent every month?"
"Is this 'Valet Trash' fee actually in my lease?"
"Did they charge me the late fee my lease specifies — or more?"
"What have I paid this year, and what's my current balance?"
The assistant answers by calling tools that do exact arithmetic in Python
(every amount is a Decimal,
never a float) and by comparing your ledger line-by-line to your lease —
instead of eyeballing a table in its context window and guessing.
Why
Ask an LLM to "total my fees for Q2" or "check my rent against my lease" from a pasted statement and you get plausible, confidently-wrong numbers. LedgerMCP moves the numbers and the comparisons out of the prompt and behind tools:
The model decides what to ask (
check_rent_charges,find_unexpected_charges, …).LedgerMCP decides what the answer is, deterministically, in Decimal — and shows its work by quoting the exact lease text it relied on.
Related MCP server: andon
Features
Renter-first workflow — import a rent ledger and a lease, then cross-examine.
Lease parsing (PDF) — heuristically extracts rent, deposit, term dates, due day, late-fee policy, recurring fees and parties, each with a confidence level and the source excerpt. The full lease text is retained so the assistant can read anything the heuristics miss.
Deterministic cross-examination — rent checks, unexpected-charge audits, deposit and late-fee comparisons, all exact.
Pluggable ledger parsers — CSV/TSV and the Excel "Full Ledger" rent-portal export out of the box; add QuickBooks/OFX/QIF/Xero by writing one small class.
SQLite storage with lossless Decimal (amounts stored as integer cents).
Classic analytics too — balances, category/monthly rollups, income statement, balance sheet.
MCP server (FastMCP) + a Typer CLI over one shared service layer.
Idempotent ledger imports, high test coverage, Ruff, Pyright, GitHub Actions CI.
MCP tools
Lease cross-examination
Tool | Description |
| One-call cross-examination: lease terms + every check + human-readable |
| Compare each month's rent charges to the lease's monthly rent. |
| Classify every charge category as expected / referenced / mismatch / unexpected. |
| Compare the deposit charged to the lease deposit. |
| Compare late fees charged to the lease late-fee policy. |
| Extracted lease terms, each with confidence + source excerpt. |
| Read the raw lease, or just the lines matching a query (pet rules, subletting…). |
Ledger analytics
Tool | Description |
| Filter by date, category, type, account, source, text, amount range. |
| Running balance for an account or the whole ledger, optionally as-of a date. |
| Net / inflow / outflow totals for a filtered set. |
| Spending grouped by calendar month. |
| Per-category rollup, ranked by spend. |
| Accrual-basis P&L for a period. |
| Assets / liabilities / equity as of a date. |
| The chart of accounts and each account's type. |
Installation
LedgerMCP uses uv.
git clone https://github.com/luke-nielsen/ledger-mcp.git
cd ledger-mcp
uv syncQuickstart
# 1. Import your rent ledger
uv run ledger-mcp import examples/sample_ledger.csv --db ledger.db
# 2. Import your lease
uv run ledger-mcp import-lease examples/sample_lease.pdf --db ledger.db
# 3. See what the lease says
uv run ledger-mcp lease --db ledger.db
# 4. Cross-examine ledger vs lease
uv run ledger-mcp lease-report --db ledger.dbThe bundled example intentionally shows a clean rent match, a late-fee discrepancy (lease says $75, ledger charged $50), and coverage gaps (a deposit and pet rent that were never charged):
LEASE vs LEDGER
Findings:
• 'Late Fee' charged $50.00 but lease specifies $75.00.
• Lease items not seen in the ledger: Security Deposit, Pet Rent.
• Late fees charged $50.00 but lease late fee is $75.00.
Rent check:
2026-04 charged $1,450.00 expected $1,450.00 [match]
2026-05 charged $1,450.00 expected $1,450.00 [match]
2026-06 charged $1,450.00 expected $1,450.00 [match]You can also import a real Excel rent-portal statement and your real lease:
uv run ledger-mcp import "full_ledger.xlsx" --db ledger.db
uv run ledger-mcp import-lease "my_lease.pdf" --db ledger.dbUse it with an AI assistant (the point)
Run the MCP server and point any MCP client at it. For Claude Desktop, add to
claude_desktop_config.json:
{
"mcpServers": {
"ledger": {
"command": "uv",
"args": ["run", "ledger-mcp", "serve"],
"cwd": "/absolute/path/to/ledger-mcp",
"env": { "LEDGER_MCP_DB": "/absolute/path/to/ledger.db" }
}
}
}Then ask: "Does my ledger match my lease?" — the assistant calls
lease_ledger_report, relays the flags, and can drill in with check_rent_charges
or get_lease_text to quote the exact clause.
Programmatic use
from ledger_mcp import LedgerService, Settings
service = LedgerService.from_settings(Settings.from_env(db_path="ledger.db"))
service.import_file("examples/sample_ledger.csv")
service.import_lease("examples/sample_lease.pdf")
report = service.lease_report()
for flag in report.flags:
print("•", flag)How lease cross-examination works
Lease PDFs are unstructured and vary wildly, so LedgerMCP splits the problem:
Extraction is heuristic but honest. Regex/keyword rules pull the common fields; each extracted value carries a
Confidence(high/medium/low) and the verbatimexcerptit came from. Whatever isn't matched is simply left unset.The full lease text is retained, so a client can read anything the heuristics miss via
get_lease_text(pet policies, subletting, maintenance).The comparisons are deterministic. Every check below is exact Decimal arithmetic over stored data — the terms may be fuzzy, but the math isn't:
Check | What it does |
Rent | Sums each month's rent charges and compares to the lease's monthly rent (match / over / under / missing). |
Charge audit | Matches each charge category to base rent, the deposit, a named lease fee, or a mention in the lease text; anything else is unexpected. Flags amount mismatches. |
Deposit | Compares the deposit charged in the ledger to the lease deposit. |
Late fees | Compares late fees charged to the lease late-fee amount and grace period. |
Notes:
National Apartment Association (NAA) leases — the most common US apartment lease — are handled by a dedicated extractor. Signed NAA packets are flattened forms whose fill-in values are detached from their labels in the text, so LedgerMCP reads the reliably-anchored fields (base monthly rent, landlord, tenants, address, effective date) and leaves the positionally ambiguous ones (deposit, late fee) for
get_lease_textrather than guessing.Scanned/image-only PDFs have no text layer; OCR is out of scope and such files are reported with a clear error. Export a text-based PDF if you can.
For unusual leases, lean on
get_lease_textand the confidence levels.
The ledger data model
Entry types and the sign convention
Every source line normalizes to one EntryType, signed by a single rule:
| Meaning | Sign on balance |
| Billed to you |
|
| You paid |
|
| Concession/discount in your favour |
|
| Money returned to you |
|
| Manual correction |
|
A positive ledger balance means money is owed.
Classification (chart of accounts)
The default ClassificationRuleset reflects a renter's perspective: charges →
one expense account per category, concessions → income, payments/refunds
→ a liability (Accounts Payable). Override per category — e.g. treat a
security deposit as an asset:
from ledger_mcp import ClassificationRuleset, AccountType
ruleset = ClassificationRuleset(category_overrides={"security deposit": AccountType.ASSET})Architecture
Layers are decoupled so each is independently testable and swappable:
ledger files ─▶ parsers ─▶ RawEntry ─▶ validate + normalize + classify ─▶ Transaction ─┐
▼
lease PDF ─────▶ lease.pdf ─▶ lease.extract ─▶ LeaseTerms ─────────────────▶ SQLite (SQLAlchemy)
│
┌────────────────────────────────────────────────────────────── ┘
▼
analytics + lease.review (cross-examination)
│
▼
LedgerService ← shared by the MCP server & CLIModule | Responsibility |
| Read ledger formats → |
| Canonical Pydantic models, enums, sign convention. |
| Map entries onto a chart of accounts and apply signs. |
| Semantic checks + reconciliation against reported balances. |
| The parse → validate → normalize → persist pipeline. |
| SQLAlchemy schema, engine, repositories. |
| PDF text extraction, heuristic term extraction, storage, and cross-examination. |
| Deterministic Decimal queries and statements. |
| Application facade owning session lifecycle. |
| FastMCP server exposing the tools. |
Adding a ledger parser
from pathlib import Path
from ledger_mcp.models import RawEntry
from ledger_mcp.parsers import ParseResult, default_registry
class QifParser:
name = "qif"
def can_parse(self, path: Path) -> bool:
return path.suffix.lower() == ".qif"
def parse(self, path: Path) -> ParseResult:
entries: list[RawEntry] = ... # read the file
return ParseResult(entries=entries, source_name=path.name, parser=self.name)
default_registry.register(QifParser())Validation, classification, storage, analytics and lease cross-examination are all format-agnostic, so nothing else changes.
Development
uv sync
uv run pytest # tests
uv run ruff check . # lint
uv run ruff format . # format
uv run pyright # type checkCI (.github/workflows/ci.yml) runs lint, type-check and tests on every push and PR.
Configuration
Variable | Meaning | Default |
| SQLite path or SQLAlchemy URL |
|
The CLI --db flag overrides the environment.
Privacy
Everything runs locally. Your ledger and lease live in a local SQLite file; no
data leaves your machine. The bundled examples/ are synthetic.
License
MIT — see LICENSE.
Available Tools
15 toolscheck_late_feesA
Compare late fees charged in the ledger to the lease late-fee policy.
Inputs: no named parameters. Returns: object
check_rent_chargesB
Compare each month's rent charges in the ledger to the lease's monthly rent.
Flags months that are overcharged, undercharged or missing a rent charge.
Inputs: end, start. Returns: object
check_security_depositA
Compare the security deposit charged in the ledger to the lease deposit.
Inputs: no named parameters. Returns: object
find_unexpected_chargesA
Audit every ledger charge category against the lease.
Classifies each category as expected (rent/deposit/named fee), referenced (mentioned in the lease text), amount_mismatch, or unexpected (not found in the lease at all), and lists lease items never charged.
Inputs: no named parameters. Returns: object
get_account_balanceA
Get the running balance for an account, or the whole ledger.
Omit account for the overall outstanding balance. as_of (YYYY-MM-DD)
limits to transactions on or before that date.
Inputs: as_of, account. Returns: object
get_balance_sheetC
Balance sheet (assets, liabilities, equity) as of a date.
Inputs: as_of. Returns: object
get_income_statementA
Accrual-basis income statement (profit & loss) for a period.
start/end are inclusive ISO dates; omit for all data.
Inputs: end, start. Returns: object
get_lease_summaryA
Get the lease terms extracted from the tenant's lease.
Returns rent, deposit, term dates, due day, late-fee policy, recurring fees and parties — each with a confidence level and the source excerpt it was read from. Low-confidence values should be verified with get_lease_text.
Inputs: no named parameters. Returns: object
get_lease_textA
Read the raw lease text, or only the lines matching query (with context).
Use this to answer questions the structured terms don't cover (pet rules, subletting, maintenance) or to verify an extracted value against the source.
Inputs: query. Returns: object
lease_ledger_reportA
Full lease-vs-ledger cross-examination in one call.
Bundles the lease terms, rent check, charge audit, deposit and late-fee
checks, plus a flags list of human-readable findings to relay to the user.
Start here for open-ended questions like 'is my ledger consistent with my lease?'.
Inputs: end, start. Returns: object
list_accountsA
List the chart of accounts with each account's type.
Inputs: no named parameters. Returns: object
monthly_spendingC
Total spending (charges/expenses) per calendar month.
Optionally restrict to a year and/or category.
Inputs: year, category. Returns: object
search_transactionsA
Search ledger transactions with flexible filters.
Filters combine with AND. entry_types accepts charge/payment/credit/
refund/adjustment. Amount bounds apply to the signed amount. Returns the
matching transactions (newest first) and a count.
Inputs: text, limit, source, account, +6 more. Returns: object
sum_transactionsB
Sum a filtered set of transactions.
Returns net (signed total), outflow (charges) and inflow
(payments/credits) magnitudes, and a count.
Inputs: text, source, account, date_to, +3 more. Returns: object
transactions_by_categoryC
Summarise activity per category, ordered by spending descending.
Inputs: date_to, date_from, entry_types. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool has a clearly distinct purpose: separate audit checks for late fees, rent, deposit, and unexpected charges; distinct financial statements; lease retrieval and report generation; and various transaction queries. No two tools overlap significantly in function.
Most tools follow a verb_noun pattern (e.g., check_rent_charges, get_balance_sheet, search_transactions). Exceptions include monthly_spending (adjective+noun) and transactions_by_category (noun_preposition_noun), but these are still clear and predictable.
With 15 tools, the set is well-scoped for a domain covering lease analysis, ledger auditing, financial reporting, and transaction search. Each tool serves a specific purpose without unnecessary bloat or gaps.
The tools cover the full lifecycle of lease-vs-ledger analysis: reading lease terms (summary and raw text), checking each major component (rent, deposit, late fees, unexpected charges), generating financial statements, and querying transactions with multiple filters and aggregations. The convenience tool lease_ledger_report bundles the core checks, making the surface complete for its intended use.
Maintenance
Related MCP Connectors
Audit a landlord's CAM reconciliation against the lease. Finds overcharges with clause citations.
Check US leases for red flags and look up verified state tenant law with statute citations.
Income and rent calculators, pay stub math checks, and bank-based income analysis tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables querying, extracting terms, and projecting rent from commercial lease documents via MCP tools.-
- AlicenseNot gradedqualityCmaintenanceDeterministic verification for AI-generated analysis. Reconciliation, consistency and Excel-integrity checks that stop the line when the numbers don't add up.54 PyPI1MIT
- AlicenseNot gradedqualityBmaintenanceEnables tenants to report rental repair issues by voice and landlords to be notified instantly, keeping both sides on one append-only, hash-chained timeline with photos, follow-ups, disputes, and dated response-time reports that neither party can quietly alter.MIT
- FlicenseNot gradedqualityBmaintenanceEnables auditing recurring bank and card subscription charges to detect stealth price increases, expired trial conversions, and calculate annualized budget leakage. It also generates retention negotiation dispute letters to help users reduce unnecessary expenses.7-