receipts-api-mcp

FastAPI receipts statistics server with a built-in MCP layer and a self-contained GitHub Pages testing dashboard.

Live dashboard (no setup required): https://chf3198.github.io/receipts-api-mcp/

The dashboard loads CSV data directly from this repository and processes everything in the browser. No server, no account, no cold start — open the link and it works.

Overview

Data source: data/receipts_2025_01.csv + data/receipts_2025_02.csv (also served from docs/data/ for the dashboard).

Related MCP server: pgEdge Postgres MCP Server

Quick Start

Prerequisites

Install uv (replaces pip + venv):

curl -LsSf https://astral.sh/uv/install.sh | sh

Run locally

git clone https://github.com/chf3198/receipts-api-mcp.git
cd receipts-api-mcp
uv sync
uv run uvicorn receipts_api.main:app --reload

Or via the project script:

uv run receipts-api

API is live at http://localhost:8000
Interactive docs: http://localhost:8000/docs

API Endpoints

Filters (all endpoints)

/receipts/stats — grouping

?group_by=company · ?group_by=product_category · ?group_by=company,product_category

Returns receipt_count, sum/avg/min/max_total_usd, sum_discount_usd, sum_tax_usd per group.

MCP Connection

Connect any MCP-compatible client (Cursor, Claude Desktop, etc.) to the running server:

{
  "mcpServers": {
    "receipts-api": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

All five receipt endpoints are auto-exposed as MCP tools with full parameter schemas.

Development

uv sync --extra dev   # installs pytest + httpx
uv run pytest -v      # run test suite (16 smoke tests)
uv run ruff check .   # lint
uv run ruff format .  # format

Security

This is a public, read-only demo API — authentication is intentionally absent by design.

A full Phase-0 security audit (threat model, automated scans, cross-family fleet red-team) completed 2026-06-08. See SECURITY.md for the full posture report.

Project Structure

receipts-api-mcp/
├── src/
│   └── receipts_api/
│       ├── main.py            # FastAPI app, CORS, MCP mount, entrypoint
│       ├── data_loader.py     # CSV → shared in-memory list
│       ├── utils.py           # shared filter + serialise helpers
│       └── routers/
│           ├── receipts.py    # /receipts endpoints
│           └── stats.py       # /receipts/stats grouped aggregates
├── data/                      # CSV source files (API runtime reads here)
├── docs/                      # GitHub Pages dashboard (zero-build HTML/JS)
│   ├── assets/                # dashboard images
│   ├── data/                  # CSV copy for browser fetch (Pages same-origin)
│   └── index.html             # self-contained dashboard
├── assets/
│   └── interview/             # original interview brief + setup instructions
├── tests/
│   └── test_api.py            # 16 pytest smoke tests (TestClient)
├── pyproject.toml             # uv + ruff + pytest config
├── uv.lock                    # deterministic lockfile
└── .python-version            # pins Python 3.11 for uv

Data Layout

The CSV data exists in two locations intentionally — each serves a different consumer:

These two copies must remain in sync. The assets/interview/ folder contains the original interview brief and setup instructions (not consumed by any runtime).