roas-to-cash-mcp
README.md
# 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`.
<p align="center">
<img src="docs/assets/readme-header.svg" width="100%" alt="roas-to-cash-mcp — Deterministic ROAS-to-Net-Cash SQLite Reconciliation Engine & MCP Server">
</p>
<p align="center">
<a href="#quick-start">Quick Start</a>  · 
<a href="#documentation">Documentation</a>  · 
<a href="#why-it-exists">Why It Exists</a>  · 
<a href="#comparison">Comparison</a>  · 
<a href="#architecture">Architecture</a>  · 
<a href="#benchmarks">Benchmarks</a>  · 
<a href="#faq">FAQ</a>  · 
<a href="#who-built-it">Who Built It</a>  · 
<a href="#feedback">Feedback</a>
</p>
<p align="center">   </p>
---
## 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`](./llms.txt).
### 1. Let Your AI Agent Install It For You (1-Click Copy)
```text
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)
```sh
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)
```json
{
"mcpServers": {
"roas-to-cash-mcp": {
"command": "python3",
"args": [
"-m",
"roas_to_cash.mcp_server",
"--mcp"
]
}
}
}
```
### 4. Programmatic SDK / CLI Usage
```python
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
```
## Documentation
- **[Getting Started & Full Setup Guide](./docs/getting-started.md)** — Step-by-step installation, configuration, and examples
- **[AI Agent Context (`llms.txt`)](./llms.txt)** — Single-fetch `<1,500`-token SDK, CLI & architecture reference
- **[MCP Registry Manifest (`server.json`)](./server.json)** — Official `stdio` tool & registry metadata
<a id="why-it-exists"></a>
## 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
| Feature | `roas-to-cash-mcp` | Triple Whale | HubSpot Attribution | Northbeam |
| :--- | :--- | :--- | :--- | :--- |
| **Joins Stripe refunds, processor fees & labor COGS** | **Yes (SQLite waterfall)** | Partial | CRM booked only | Ad-centric |
| **Catches intra-platform + cross-channel deal overlap** | **Yes (Exact `deal_id` proof)** | Model-weighted | Tier-gated | Model-weighted |
| **100% local CSV execution (`0` cloud pixels)** | **Yes (`0` dependencies)** | Cloud SaaS | Cloud SaaS | Cloud SaaS |
| **Native `stdio` MCP Server + `SKILL.md`** | **Yes (Apache-2.0)** | Paid API tier | No | No |
## Architecture
```text
ad_spend.csv + crm_deals.csv + ledger_settlements.csv -> [SQLite Foreign-Key Loader] -> [Overlap & Unpaid Detector] -> [Refund/Fee/Labor Waterfall] -> JSON / MCP Report
```
## Benchmarks
| Metric | Measured Value | Conditions |
| :--- | :--- | :--- |
| 3-CSV SQLite load + waterfall query latency | `1.35ms` | In-memory SQLite foreign-key join on standard laptop CPU |
| Auxiliary daemon / GPU VRAM footprint | `0 MB VRAM` | Pure Python 3.10+ stdlib (`csv`, `sqlite3`, `json`) |
| MCP tool schema + `llms.txt` context budget | `740 tokens` | Compact `<1,500`-token discovery footprint for AI coding & finance agents |
## 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
<img src="https://github.com/cynthiaschomp.png?size=264" width="124" align="left" alt="Cynthia Schomp">
**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](https://github.com/cynthiaschomp)  ·  [Website](https://cynthiaschomp.com)  ·  [Contact](https://cynthiaschomp.com/contact/)
<br clear="left">
---
## Feedback
Questions, bug reports, benchmark comparisons, or ideas for what you need next? [Open an issue](https://github.com/cynthiaschomp/roas-to-cash-mcp/issues) or start a thread in [Discussions](https://github.com/cynthiaschomp/roas-to-cash-mcp/discussions)—real-world developer feedback directly shapes the roadmap.
License: [Apache-2.0](./LICENSE) · Attribution required via [`NOTICE`](./NOTICE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues