Building a Local AI-Powered Receipt Sorter with Tiger Cloud and MCP for Freelancers

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle Submission 💸

During this Global Hack Week and Hacktoberfest challenge, I wanted to build something practical that solves a real-world problem for small business owners and freelancers. Receipts, invoices, and expense tracking are often tedious tasks, and relying on heavy cloud-based AI APIs can risk sensitive client data while incurring recurring costs.

To solve this, I built Local AI Receipt Sorter—a local-first tool powered by open-source AI logic, secure database partitioning, and Model Context Protocol (MCP) integration with Tiger Cloud.

1. Project Folder Structure

To keep the application modular, clean, and easy to maintain, the project follows a standard production-ready folder layout:

local-ai-receipt/
│
├── .env.example            # Environment variables template (Database URLs, API keys)
├── .gitignore              # Files and folders to ignore in Git
├── README.md               # Comprehensive project documentation
├── requirements.txt        # Python dependencies (psycopg2, requests, etc.)
│
├── config/
│   └── mcp_config.json     # Tiger MCP configuration for AI assistant integration
│
├── src/
│   ├── __init__.py         # Package initializer
│   ├── database.py         # Tiger Cloud / TimescaleDB connection and hypertable setup
│   ├── parser.py           # Local text parsing and receipt data extraction logic
│   └── main.py             # Main entry point running the receipt sorting pipeline
│
└── data/
    └── sample_receipts.txt # Sample raw text data used for testing and processing

2. System Architecture & Data Flow

Here is how the components interact locally and communicate with the Tiger Cloud database via MCP:

[ Raw Receipt / Invoice Text ]
               │
               ▼
  ┌─────────────────────────┐
  │   src/parser.py         │  <--- Local Regex / Open-Weight Parsing
  └────────────┬────────────┘
               │
               ▼
  ┌─────────────────────────┐
  │   src/database.py       │  <--- Tiger Cloud (TimescaleDB Hypertable)
  └────────────┬────────────┘
               │
               ▼
  ┌─────────────────────────┐
  │   Tiger MCP & Agent     │  <--- Natural Language Queries via AI Assistant

3. Step-by-Step Technical Implementation

Step 1: Database Hypertable Setup (src/database.py)

In Tiger Cloud, time-series financial logs are structured into hypertables for efficient indexing and scaling. The database script initializes the table schema:

`CREATE TABLE IF NOT EXISTS receipts (
id SERIAL,
vendor_name TEXT,
category TEXT,
total_amount NUMERIC,
created_at TIMESTAMPTZ NOT NULL
);

-- Converting to a TimescaleDB hypertable for optimized time-series storage
SELECT create_hypertable('receipts', 'created_at', if_not_exists => TRUE);`

Step 2: CLI & MCP Integration

To link local development tools with Tiger Cloud securely and manage records via conversational prompts:

tiger auth login
tiger mcp install

This automatically wires the Model Context Protocol (MCP) configuration into your AI development environment (config/mcp_config.json), allowing instant natural language querying of stored receipts.

4. Why Open Innovation Won Here

Zero Data Leakage: Financial information remains fully partitioned and secure under local and trusted database environments without exposing raw client data to third-party model servers.
Cost Efficiency: By avoiding expensive third-party hosted API inference calls for basic structuring, the solution costs virtually nothing to run.
Scalability: Tiger Cloud's time-series hypertable architecture ensures lightning-fast queries even as thousands of monthly receipts accumulate.

Conclusion & Next Steps

Building this side-hustle utility proved how powerful open-weight models, local toolings, and Tiger Cloud MCP can be when combined. I have already tested it with a local freelancer friend who found it immensely helpful for tax season preparation!

Check out the repository on GitHub: SithubShabihaz/local-ai-receipt

Happy coding, and let's keep building open! #mlhacks #devchallenge #hf26challenge #tigerdata

DEV Community