Skip to main content
Glama
Ledger MCP

Ledger MCP

by DiogoS7

Ledger MCP

CI

Ask an AI assistant about card fraud, and let it check the answers in the data.

An MCP server for Ledger, my project on a year of card payments at Meridian Bank, a made-up Portuguese bank: 430,000 payments, three kinds of planted fraud, and six SQL checks that score every payment.

With this server, Claude (or any MCP client) can:

  • answer questions about the data: "Which country do stolen cards get used in most?"

  • explain a decision: "Why was payment 406064 blocked? Was it really fraud?"

  • find the mistakes: "Show me the biggest frauds the checks missed."

  • try changes before making them: "What if we block at 50 points instead of 60?"

It doesn't copy anything from Ledger. It imports the ledger package from a Ledger checkout, so the checks, scoring and points system are the same code that builds the report.

Tools

Tool

What it does

ledger_overview

Headline numbers: customers, payments, money spent, fraud losses, thresholds

describe_schema

Tables, columns, row counts and the commented schema

list_analyses / run_analysis

The 10 ready-made SQL analyses behind the report (category mix, contactless trend, fraud hotspots, time to report, ...)

query_sql

Any read-only SELECT / WITH query, capped at 500 rows and 20 seconds

list_checks

The six checks in plain words, with their points, settings and SQL

check_scorecard

Precision, recall and euros caught, for each check and for the combined points system

try_check_setting

Re-run one check with one setting changed and compare (e.g. R1 min_txns 4 → 3)

try_thresholds

Change the review/block thresholds and see fraud caught vs genuine customers stopped

explain_payment

One payment in full: shop, card, customer, checks tripped with evidence, score, decision, and whether it really was fraud

card_activity

A card's payments in order, optionally around one payment (to spot test charges or a trip abroad)

find_payments

Example payments by outcome: caught, missed, false_alarm, reviewed

It also has two resources (ledger://schema, ledger://checks) and two prompts (investigate_payment, tune_the_checks).

Every tool is read-only. The database is opened with SQLite's mode=ro. query_sql also uses an authorizer that only allows reads, so writes, ATTACH, PRAGMA and extension loading are refused even if they get past the single-statement check. The what-if tools change settings for that call only and save nothing.

Related MCP server: Company Data MCP Server

Example

You: Why was payment 406064 stopped?

Claude (calls explain_payment, then card_activity): It was a €1,495 online purchase at an electronics shop at 4:53 in the morning, on the debit card of a customer aged 65+ from Lisboa. Two checks fired. Unusually big payment (+30): it was 14.4× this card's usual €103.90. Late-night risky shop (+35): electronics, at 04:53. That makes 65 points, over the 60 needed to block it. The customer reported it as fraud five days later, so blocking it was right. This looks like a hijacked account.

What the tools return on the full dataset:

try_thresholds(review_at=30, block_at=50)
  current : blocked automatically 77.2% of stolen €, 93.6% with review
  what-if : blocked 389 payments, 253 of them genuine customers ...

try_check_setting("R4", "multiple", 12)
  current (8×) : 3,517 alerts, precision 2.8%, catches 78.7% of stolen €
  what-if (12×): 1,626 alerts, precision 4.4%, catches 62.1% of stolen €

Set it up

Needs Python 3.12+, git and uv.

1. Get Ledger and build its database (one time, about a minute):

uvx --from git+https://github.com/DiogoS7/Ledger-MCP ledger-mcp setup

This clones Ledger into ~/.ledger-mcp/Ledger and generates data/ledger.db. If you already have a checkout, set LEDGER_HOME to it (and run python -m ledger generate there if there's no database yet).

2. Add it to your MCP client.

Claude Code:

claude mcp add ledger -- uvx --from git+https://github.com/DiogoS7/Ledger-MCP ledger-mcp

Claude Desktop (claude_desktop_config.json), or any client that takes the same format:

{
  "mcpServers": {
    "ledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiogoS7/Ledger-MCP", "ledger-mcp"],
      "env": { "LEDGER_HOME": "/path/to/Ledger" }
    }
  }
}

env is optional. Without it the server uses ~/.ledger-mcp/Ledger. Set LEDGER_DB to use a database somewhere else.

How it works

MCP client (Claude)
   │  stdio
   ▼
ledger_mcp/server.py      12 tools · 2 resources · 2 prompts   (mcp 2.x MCPServer)
   │  imports
   ▼
Ledger checkout           ledger.rules  → the six checks, scoring, thresholds
($LEDGER_HOME)            ledger.db     → runs sql/analysis/*.sql and sql/rules/*.sql
   │  read-only
   ▼
data/ledger.db            customers · cards · merchants · transactions · chargebacks

The first call that needs the checks runs all six over the 430k payments (about 7 seconds) and keeps the result in memory until the database file changes. After that, explain_payment, find_payments and try_thresholds answer instantly. try_check_setting re-runs a single check, which takes about 3 seconds.

Develop

git clone https://github.com/DiogoS7/Ledger-MCP && cd Ledger-MCP
git clone https://github.com/DiogoS7/Ledger ../Ledger
LEDGER_HOME=../Ledger uv run pytest -q

The tests build a small Ledger database (250 customers) and talk to the server through an in-memory MCP client. They cover every tool, both resources, a prompt, and the read-only guarantees. To try it by hand, use the MCP Inspector: npx @modelcontextprotocol/inspector uv run ledger-mcp.

The data is synthetic. No real people or banks are involved.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables real-time fraud detection and transaction analysis by integrating with Claude through MCP, providing tools to analyze transactions, flag suspicious activity, and manage fraud rules.
      9
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to company data across PostgreSQL, MongoDB Atlas, and flat files through MCP tools, allowing AI assistants to query and retrieve information via natural language.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query internal business data for insights into customers, revenue, subscriptions, sales, and churn through controlled, read-only MCP tools.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to interrogate payment routing decisions through six tools: route transactions, explain decisions, simulate scenarios, inspect segment evidence, normalize decline codes, and review backtest summaries. It provides read-only access to the routing engine, allowing natural-language queries without modifying any decisions.
      MIT