ledger-mcp

A small MCP server exposing a double-entry ledger as tools for AI agents. Built as a two-day exercise in MCP server design, agent tool ergonomics, and eval-driven iteration.

Status: Day 1 complete. Day 2 (eval harness + findings) in progress.

What's here

• ledger.py — double-entry ledger core, backed by SQLite. Amounts stored as integer cents. Enforces balanced transactions and named-account integrity.

• server.py — MCP server exposing four tools: create_account, record_transaction, get_balance, reconcile.

• test_ledger.py — pytest suite for the ledger core.

• NOTES.md — running log of design decisions and observations from running the server against Claude Desktop.

Related MCP server: Agent Ledger

Run locally

uv sync
uv run pytest -v          # run the ledger tests
uv run mcp dev server.py  # launch with the MCP Inspector

To use with Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "ledger": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ledger-mcp", "run", "mcp", "run", "server.py"]
    }
  }
}

Coming Day 2

• Eval harness measuring where agents succeed and break on these tools

• Findings write-up: naming vs. documentation, silent account creation, tool-as-guardrail vs. tool-as-executor