Receipt Splitter
Receipt Splitter is a local stdio MCP server for turning receipt photos into reviewed, per-person expense splits.
split_receipt: validate, preprocess, OCR, and parse a PNG/JPEG receipt (optionaltax_included).provide_assignments: map receipt row IDs to people's names.finalize_split: settle the split when validation reports ready.reset: clear the current session.help_receipt: get usage help.README flow also includes
correct_rowfor fixing item names, quantities, line totals, or tax applicability, though it isn't listed in the given schema.Runs locally over stdio, keeps photos private, and enforces input-folder/session/OCR limits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Receipt Splitter Split the receipt photo in my input folder between me and Jamie"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Receipt Splitter
Receipt Splitter is a local MCP server for turning a receipt photo into a checked, per-person expense split. It runs over stdio and does not expose a web server.
Receipt parsing is heuristic. Review the recognized rows and totals before settling a bill. When an image is unclear or an assignment is ambiguous, use a better photo or assign the stable row ID.
Requirements
macOS on Apple silicon or Intel
Python 3.13 or 3.14
Tesseract 5.x (
brew install tesseract); verified locally with Tesseract 5.5.1
PaddleOCR is available as an optional alternative on Python 3.13. The default install uses Tesseract and does not download Paddle models.
Related MCP server: splitwise-mcp
Install and run
uv sync --locked
mkdir -p "$HOME/Documents/Receipt Splitter/Inputs"
uv run receipt-splitterThe MCP client should launch uv run receipt-splitter from this checkout. The compatibility command
uv run python main.py starts the same stdio server.
To use a different input folder, set RECEIPT_ALLOWED_ROOT to its absolute path before launch. Only
PNG and JPEG files inside that folder are accepted. Files are checked by extension, decoded format,
byte size, and pixel count. Preprocessed derivatives live in a private temporary directory and are
removed after OCR.
Optional Paddle setup:
uv python pin 3.13
uv sync --locked --extra paddle
RECEIPT_OCR_ENGINE=paddle uv run receipt-splitterPython 3.14 installs omit the Paddle dependencies because the locked Paddle runtime has no 3.14 wheel. Selecting Paddle on 3.14 returns a configuration error instead of silently falling back.
MCP flow
Call
split_receiptwith an image inside the configured input folder.Review every row and the validation report.
Use
correct_rowfor a wrong item name, quantity, line total, or tax applicability.Call
provide_assignmentswith row IDs mapped to names.Call
finalize_split; settle only when it reportsready: true.Call
resetafter the split is complete.
Duplicate names are kept as separate rows. Fuzzy matches that are unclear remain unresolved. Tax is allocated in whole cents. Finalization separately proves that the sum of every person's total equals the recognized receipt total.
The amount at the end of an item row is always treated as that row's line total. A printed quantity
is retained as metadata; Receipt Splitter does not guess whether a store printed a unit price or
multiply the amount by quantity. Use correct_row when OCR captured either field incorrectly.
OCR is limited to one concurrent job by default. Tesseract receives a 30-second timeout, callers
wait up to five seconds for OCR capacity, and timed-out background work keeps its slot until it
actually exits. Set RECEIPT_OCR_TIMEOUT_SECONDS from 1 to 300,
RECEIPT_OCR_QUEUE_TIMEOUT_SECONDS from 1 to 60, or RECEIPT_MAX_CONCURRENT_OCR from 1 to 4 before
launch. Invalid values fail at startup.
Privacy
Receipt photos stay on the machine. The server does not upload them, log their contents, or retain
preprocessed copies. Sessions expire after two hours and are limited to 32 active clients by
default. RECEIPT_SESSION_TTL_SECONDS accepts 60 to 86,400 seconds and
RECEIPT_MAX_SESSIONS accepts 1 to 256.
Keep real receipts outside the checkout. Root-level images and common input/output folders are ignored as a second line of defense. The repository fixture is fictitious text.
Verify
uv sync --locked --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy receiptsplitter tests
uv run pip-audit
uv run python scripts/check_release_privacy.py
uv buildCI runs the same checks, scans the Git history for secrets, and builds the package. See
RELEASE_READINESS.md for recorded release evidence.
License
Copyright (c) 2026 Gaurav Dama. Released under the MIT License. Third-party software keeps
its own license; distribution notes are in NOTICE.md.
Available Tools
5 toolsfinalize_splitD
Inputs: no named parameters. Returns: object
help_receiptD
Inputs: no named parameters. Returns: result
provide_assignmentsD
Inputs: assignments (required). Returns: object
resetD
Inputs: no named parameters. Returns: result
split_receiptB
Validate, privately preprocess, OCR, and parse a PNG or JPEG receipt.
Inputs: image_path (required), tax_included. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Tool names suggest distinct workflow stages, but four tools lack descriptions, leaving some ambiguity around reset vs. help_receipt and how provide_assignments differs from finalize_split. split_receipt is clearly unique.
All tools follow a consistent verb_noun pattern: reset, split_receipt, provide_assignments, finalize_split, help_receipt. Naming is predictable and uniform.
Five tools is well-scoped for a focused receipt splitting workflow, covering reset, processing, assignment, finalization, and help without redundancy.
The workflow appears complete for the core receipt splitting process: reset state, split the receipt, provide assignments, and finalize. Minor gaps like explicit result retrieval or cancellation are absent but not essential for the domain.
Maintenance
Related MCP Connectors
Split a restaurant receipt by item and get exact totals. No sign-in needed.
61Split bills from your AI: read bills & balances, create equal splits, request settlements.
Add, view or search your receipts, split the spend with friends and manage balances.
Track expenses from receipt photos, then search, summarize and update them from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Splitwise expenses with atomic duplicate prevention, smart fuzzy matching, and support for flexible split ratios between two people.MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language management of Splitwise expenses, groups, and friends via the Model Context Protocol, with dual authentication and fuzzy name resolution.19MIT
- AlicenseAqualityCmaintenanceEnables managing Splitwise expenses and generating premium spending analytics with category breakdowns, trends, and settlement optimization through natural language.42MIT
- FlicenseNot gradedqualityCmaintenanceHosted MCP service for receipt capture, Gmail scanning, expense search and reviewed reporting. Connect at https://mcp.expensebot.ai/mcp; no server deployment required. Sign in to ExpenseBot for account workflows.-