Skip to main content
Glama
Risk Rule Mining MCP

Risk Rule Mining MCP

by mrezamoosavi

Risk Rule Mining MCP

Mine interpretable risk rules from relational financial data, with Claude as the interface.

CI status license python

An open-source Model Context Protocol server that searches relational data for simple, explainable rules (alpha-mining style), scores them honestly, and reports what they are worth. One shared rule engine, four risk domains.

Status: early development. The data layer for credit works today; rule mining tools land use case by use case. Sections marked TODO fill in as the roadmap progresses.


Why

Risk teams live on rules: they are auditable, explainable to regulators, and cheap to run. Finding good ones is still mostly manual. This project automates the search, then holds every rule to the same bar: out-of-time validation, minimum support, stability over time, and a dollar estimate of impact.

Related MCP server: Store Assistant MCP Server

Design principles

  • Runs fully local. No hosting, no cloud services, no custom UI. Claude (or any MCP client) is the interface.

  • Relational first. Sits on a real relational database with primary and foreign keys. DuckDB by default, so no Docker is needed; Postgres optional.

  • Interpretable by construction. Output is rules a person can read, not a black-box score.

  • Honest scoring. Capture rate, false positive rate, lift and precision, always on out-of-time data.

  • Every module earns its keep. Each use case ships an insights dashboard and an ROI estimate.

  • Clean-room, public data only. See Data.

Domains and use cases

#

Domain

Use case

Public data

ROI type

1

Credit

Four use cases, below

Home Credit Default Risk (7 relational tables)

Loss reduction, revenue, capital

2

Treasury

Reverse stress testing: find the combinations of rate moves, deposit outflow and funding spread that breach liquidity or NII limits

Synthetic balance sheet + Bank of Canada yield curves

Profit and capital efficiency

3

AML

Transaction-monitoring scenario tuning: typology rules (fan-in, fan-out, gather-scatter, layering) with thresholds tuned to cut false alerts

IBM AMLworld

Fewer false alerts, analyst hours saved

4

Derivatives

Futures positioning early warning: positioning patterns that come before large moves in CAD, crude and Canadian rates

CFTC Commitments of Traders + Bank of Canada

Risk avoided, hedging cost

Credit use cases

  1. Thin-file underwriting. Rules from alternative data for applicants that bureau scores serve poorly: newcomers, young borrowers, the self-employed.

  2. Credit limit management. Rules for line increases and decreases, with simulated revenue and loss impact.

  3. IFRS 9 staging and overlays. Explain what drives significant-increase-in-credit-risk staging and tie management overlays to scenarios.

  4. Vendor data profiling and signal requirements. Profile a new vendor data feed and manage the signals required from it.

TODO: detail and tools for each as it is built.

Architecture

┌──────────────┐     MCP      ┌──────────────────────────────────────────┐
│   Claude /   │ ◄──────────► │  MCP server                              │
│  MCP client  │              │  shared tools + use-case tools           │
└──────────────┘              ├──────────────────────────────────────────┤
                              │  Use-case modules                        │
                              │  labels · features · ROI logic           │
                              ├──────────────────────────────────────────┤
                              │  Shared rule engine                      │
                              │  single conditions → combinations →      │
                              │  expression search                       │
                              │  scoring · out-of-time · stability       │
                              ├──────────────────────────────────────────┤
                              │  Data layer                              │
                              │  download scripts · loaders with PK/FK   │
                              │  DuckDB (default) | Postgres (optional)  │
                              └──────────────────────────────────────────┘

MCP tools

Tool

Status

What it does

list_tables

available

Loaded tables with row and column counts

describe_table

available

Columns, types, primary and foreign keys

profile_table

planned

Nulls, distributions and join coverage

mine_rules

planned

Search for candidate rules against a target

backtest_rule

planned

Score a rule out of time

explain_rule

planned

Plain-language explanation of a rule

estimate_roi

planned

Dollar impact of a rule or rule set

build_dashboard

planned

Self-contained HTML insights dashboard

Use-case tools are added as each use case is built.

Quickstart

Needs uv. No Docker, no database server.

git clone https://github.com/mrezamoosavi/risk-rule-mining-mcp.git
cd risk-rule-mining-mcp
uv sync

# Try it in seconds on synthetic sample data (no account, no download)
uv run rrm demo
uv run rrm status

# Real data: needs a Kaggle account, see Data below
uv run rrm setup credit            # full data, about 2.5 GB
uv run rrm setup credit --quick    # about 1 applicant in 20, faster

Data and the database live in ./data (ignored by git). Set RRM_DATA_DIR to put them elsewhere.

Connect to Claude Desktop

Add this to claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config), using absolute paths. Use the full path to uv (which uv), since Claude Desktop may not see your shell's PATH.

{
  "mcpServers": {
    "risk-rule-mining": {
      "command": "/full/path/to/uv",
      "args": ["--directory", "/full/path/to/risk-rule-mining-mcp", "run", "rrm-server"],
      "env": { "RRM_DATA_DIR": "/full/path/to/risk-rule-mining-mcp/data" }
    }
  }
}

Restart Claude Desktop, then ask: "What tables are loaded, and how are they related?"

Data

No data is committed to this repository. Each domain has one command that downloads it from the original source, loads it with keys, and reports what it loaded.

Domain

Dataset

Source

License

Size

Command

Credit

Home Credit Default Risk

Kaggle competition

Kaggle competition rules: use for research and modelling, no redistribution

~2.5 GB unzipped

rrm setup credit

Treasury

Synthetic balance sheet + yield curves

Generated by this repo + Bank of Canada

MIT (generated) / Bank of Canada terms

small

TODO

AML

IBM AMLworld

Kaggle dataset

CDLA-Sharing-1.0

small variants: hundreds of MB

TODO

Derivatives

Commitments of Traders

CFTC + Bank of Canada

US government public data / Bank of Canada terms

small

TODO

Kaggle setup (credit and AML), once:

  1. Create a free account and an API token at kaggle.com/settings. Save it as ~/.kaggle/kaggle.json, or set KAGGLE_USERNAME and KAGGLE_KEY.

  2. For credit, accept the competition rules with the same account.

If something is missing, rrm setup says exactly which step to do. You can also download the zip by hand and drop it in data/raw/credit/.

How credit loads. application_train and application_test become one application table with a split column (TARGET is empty for test). Primary keys: application, bureau, previous_application. Every child table has foreign keys to its parents. Child rows whose parent doesn't exist are skipped and counted in the load report, never silently dropped.

Caveats shown on every dashboard. Home Credit has no calendar dates (days relative to the application) and is not Canadian, so ROI is calibrated to Canadian aggregates (Equifax, TransUnion, OSB). The treasury balance sheet is synthetic. CFTC data is weekly.

Clean-room build. All code, rules, features and assumptions come from public sources only. Nothing comes from any employer's code, rules, models or data.

Development

uv sync
uv run pytest            # runs on synthetic data generated at test time
uv run ruff check .

CI runs lint, tests and a CLI smoke test on Linux and macOS for every push.

Roadmap

  • 0. Foundation: repo, uv project, MCP skeleton, CI, DuckDB, credit download and load (in progress)

  • 1. Credit: thin-file underwriting, limit management, IFRS 9 staging, vendor data profiling

  • 2. Treasury: synthetic balance sheet, yield curves, reverse stress testing

  • 3. AML: AMLworld load, network features, scenario tuning, alert reduction ROI

  • 4. Derivatives: CFTC positioning, Bank of Canada context, early-warning rules

Results

TODO: headline findings and dashboards per use case.

Contributing

Issues and suggestions are welcome. This is a personal portfolio project, so larger pull requests are best discussed in an issue first.

License

MIT © 2026 Mohamad Reza Moosavi

Available Tools

4 tools
describe_tableC

Columns, types, primary key and foreign keys of one table.

Inputs: table (required).

get_metadataC

What each table is (description, grain, size, key) and how tables relate, with coverage.

Inputs: no named parameters.

list_tablesB

List loaded tables with row and column counts.

Inputs: no named parameters. Returns: result

profile_tableB

Column-by-column profile: role, description, nulls, distinct values, ranges, top values.

Reads saved metadata when `rrm profile` has been run, otherwise profiles on the fly.

Inputs: table (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 4 tools

    Disambiguation4/5

    The tools target mostly distinct metadata layers: table inventory, table schema, column profiling, and semantic/table-relationship metadata. There is minor overlap between get_metadata and list_tables/describe_table around table keys and descriptions, but the boundaries are reasonably clear from the descriptions.

    Naming Consistency5/5

    All tool names use snake_case with a leading verb and noun object: list_tables, describe_table, profile_table, get_metadata. The pattern is predictable and consistent throughout.

    Tool Count4/5

    Four tools is a compact, focused set for metadata discovery, and each tool covers a different exploration step. However, relative to a server named Risk Rule Mining, the set is somewhat thin because it only addresses metadata preparation.

    Completeness2/5

    The surface only supports table discovery, schema inspection, profiling, and metadata lookup. For a Risk Rule Mining server, there are no tools to mine, evaluate, save, or manage risk rules, leaving the core domain lifecycle unaddressed.

    Related MCP Connectors

    • Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.

      https://mcp.contextflo.com/mcp
    • Independent statistical feature evaluation for machine learning and forecasting. ML Referee tests up to 1,000 candidate features in one run against a declared baseline, helping researchers and AI agents decide which inputs to pursue, which bounded feature repairs merit further testing, and where more evidence is needed—without a separate ablation run for every feature. Use the MCP tools to discover input schemas, check access and credits, preflight a dataset, obtain a quote, submit an authorized evaluation, and retrieve structured results and reports. Results are scoped to the submitted evidence and evaluation design; they do not guarantee future model performance. Invite-only beta with manual approval. Public tool discovery requires no authentication; account and evaluation tools require OAuth through approved client connections and available evaluation credits. Connect directly to https://api.mlreferee.com/mcp. Website: https://mlreferee.com Request beta access: https://mlreferee.com/beta Agent setup and documentation: https://mlreferee.com/agents

      https://api.mlreferee.com/mcp
    • Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.

      https://autario.com/mcp
    • Ask Claude, ChatGPT, or any MCP client about your game's players, retention, revenue, and win rates.

      https://gamestats.ai/api/v1/mcp

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables governed, read-only SQL analytics, hybrid RAG knowledge search, financial metric calculation, and database schema introspection through MCP, with role-based access control, audit logging, and AI observability.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude and other MCP clients to query live online-store product, order, sales, stock, and customer data in plain English, with secure read-only defaults, masked customer information, capped results, and audit logging.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude or any MCP client to explore and query a SQL database in natural language through a governed, read-only layer. Every request is checked against per-user table permissions, column masking, enforced row limits, daily quotas, and a full audit log.
      4
      MIT