roas-to-cash-mcp — Deterministic ROAS-to-Net-Cash SQLite Reconciliation Engine & MCP Server

roas-to-cash-mcp is a zero-dependency Python SQLite engine and Model Context Protocol (MCP) server that reconciles ad-manager ROAS claims against CRM deal stages, processor settlements, refunds, fees, and fulfillment labor. Out of the box, its /demo dataset proves how a reported 4.2x Meta ROAS masks -$14,200 in net cash loss in <2ms with 0 MB VRAM.

Quick Start

No terminal wrestling required: click GitHub's Copy button on the top-right of any snippet below, or hand the single prompt in Step 1 directly to your AI coding agent (Claude Code, Cursor, Antigravity, Codex, or OpenCode) and let it handle setup end-to-end via llms.txt.

1. Let Your AI Agent Install It For You (1-Click Copy)

Install and configure https://github.com/cynthiaschomp/roas-to-cash-mcp in this project using its llms.txt and docs/getting-started.md, then run a quick check to confirm everything works.

2. Terminal Install (1-Click Copy)

git clone https://github.com/cynthiaschomp/roas-to-cash-mcp.git && cd roas-to-cash-mcp && python3 -m roas_to_cash.mcp_server --demo

3. 5-Line MCP Config (Claude Desktop, Cursor, Antigravity, OpenCode)

{
  "mcpServers": {
    "roas-to-cash-mcp": {
      "command": "python3",
      "args": [
        "-m",
        "roas_to_cash.mcp_server",
        "--mcp"
      ]
    }
  }
}

4. Programmatic SDK / CLI Usage

from roas_to_cash import reconcile_roas_to_cash

report = reconcile_roas_to_cash()
print(report["meta_reported_roas_label"], report["net_cash_usd"])
# -> 4.2x -14200.0

Related MCP server: ecommerce-mcp-automation

Documentation

• Getting Started & Full Setup Guide — Step-by-step installation, configuration, and examples

• AI Agent Context (llms.txt) — Single-fetch <1,500-token SDK, CLI & architecture reference

• MCP Registry Manifest (server.json) — Official stdio tool & registry metadata

Why Founders, Operators & Finance Teams Need This

• Ad platforms double-claim the same customer — Prospecting, retargeting, and branded search routinely claim 100% credit for identical deal_id conversions—inflating dashboard ROAS while bank balances shrink.

• CRM Closed-Won does not equal settled cash — Joins CRM invoices directly against processor settlement rows so overdue unpaid contracts and full refunds with non-refundable Stripe fees surface immediately.

• SaaS attribution tools require pixels, cloud syncs & $500+/mo contracts — Runs 100% locally in embedded SQLite over standard CSV exports via CLI or MCP (Claude Code, Cursor, Antigravity) with zero third-party data sharing.

Comparison

Architecture

ad_spend.csv + crm_deals.csv + ledger_settlements.csv -> [SQLite Foreign-Key Loader] -> [Overlap & Unpaid Detector] -> [Refund/Fee/Labor Waterfall] -> JSON / MCP Report

Benchmarks

FAQ

How do I run the 4.2x Meta ROAS vs -$14,200 net cash demo locally?

Clone the repository and run python3 -m roas_to_cash.mcp_server --demo. It loads demo/ad_spend.csv, demo/crm_deals.csv, and demo/ledger_settlements.csv into SQLite and prints the complete JSON waterfall.

How do I reconcile my own Meta Ads, CRM, and Stripe CSV exports with Claude Code or Cursor?

Register python3 -m roas_to_cash.mcp_server --mcp in mcpServers (or load SKILL.md) and pass your three local CSV file paths to roas_reconcile_csvs.

How do I inspect why a specific Closed-Won deal lost money after refunds and fulfillment labor?

Call roas_audit_deal (or --deal-id D-104 on the CLI) to see every ad campaign claiming credit for that deal alongside its Stripe settlement, refund, processor fee, and labor cost.

Who Built It

Cynthia Schomp

I run a web design, marketing, and AI systems studio—building practical software, agent infrastructure, and developer tools I need in production first, and sharing reusable building blocks openly so other builders can move faster too.

Connect: GitHub  ·  Website  ·  Contact

Feedback

Questions, bug reports, benchmark comparisons, or ideas for what you need next? Open an issue or start a thread in Discussions—real-world developer feedback directly shapes the roadmap.

License: Apache-2.0 · Attribution required via NOTICE