Receipts API MCP
chf3198/receipts-api-mcp
API de recibos com MCP nativo e dashboard web zero-setup
Ver no GitHubServidor FastAPI com camada MCP integrada para análise de recibos mensais em CSV com estatísticas SQL-style agrupadas. Inclui dashboard interativo em GitHub Pages (sem setup) e suporte a filtros avançados por empresa, categoria e período.
Instalação
npx convez-ai chf3198/receipts-api-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise de despesas e gastos pessoais/empresariais
- Prototipagem rápida de ferramentas MCP com dados reais
- Dashboard de relatórios financeiros sem infra backend
Veredito

Projeto bem-executado que demonstra padrão MCP moderno com FastAPI, traz valor imediato via dashboard em GitHub Pages e oferece API limpa para integração. Código de qualidade e documentação clara tornam relevante tanto para aprendizado quanto uso prático.
README
A tradução para o português deste README ainda está na fila.
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
| 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).