receipts-api-mcp

banner

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

Layer	Technology	Notes
Demo dashboard	Vanilla JS + Chart.js + Papa Parse (GitHub Pages)	Always-on, zero setup — visit the link above
REST API	FastAPI	Run locally: `uv run receipts-api` → `http://localhost:8000`
MCP server	fastapi-mcp (Streamable HTTP)	Available at `http://localhost:8000/mcp` when running locally

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

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

Method	Path	Description
`GET`	`/receipts`	List receipts with optional filters
`GET`	`/receipts/stats`	SQL-style grouped statistics
`GET`	`/receipts/companies`	Distinct company names
`GET`	`/receipts/categories`	Distinct product categories
`GET`	`/receipts/{receipt_id}`	Single receipt by ID

Filters (all endpoints)

Param	Type	Description
`company`	string	Exact match, case-insensitive
`product_category`	string	Exact match, case-insensitive
`date_from`	ISO date	Earliest receipt date (inclusive)
`date_to`	ISO date	Latest receipt date (inclusive)
`status`	string	e.g. `Paid`

`/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.

Aspect	Posture
CORS	`allow_origins=["*"]`, `allow_methods=["GET"]` — required for GitHub Pages dashboard access
Auth	None — all endpoints are public read-only; no PII or sensitive data
Data	Synthetic sample CSV — no real financial records or personal information
Dependencies	Audited via `pip-audit` + Dependabot — no known CVEs
CDN integrity	SRI hashes on Chart.js and PapaParse script tags
Branch protection	`master` requires PR + CI green before merge

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:

Path	Consumer	Notes
`data/`	API runtime	`data_loader.py` reads `data/*.csv` at startup; this is the source of truth for all API responses
`docs/data/`	GitHub Pages dashboard	The dashboard (`docs/index.html`) fetches CSV files via relative path in the browser; GitHub Pages same-origin policy requires a local copy under `docs/`

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

receipts-api-mcp

receipts-api-mcp

Overview

Quick Start

Prerequisites

Run locally

API Endpoints

Filters (all endpoints)

`/receipts/stats` — grouping

MCP Connection

Development

Security

Project Structure

Data Layout

Latest Blog Posts

MCP directory API

receipts-api-mcp

Overview

Quick Start

Prerequisites

Run locally

API Endpoints

Filters (all endpoints)

/receipts/stats — grouping

MCP Connection

Development

Security

Project Structure

Data Layout

Latest Blog Posts

MCP directory API

`/receipts/stats` — grouping