How do I use Receipt Splitter?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by gauravsdama

Overview Schema Source Related Servers Discussions Admin

Python

Local

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
uv
Tesseract 5.x (brew install tesseract); verified locally with Tesseract 5.5.1

PaddleOCR is available as an optional alternative. The default install uses Tesseract and does not download Paddle models.

Related MCP server: kelnix-receipt-mcp-api

Install and run

uv sync --locked
mkdir -p "$HOME/Documents/Receipt Splitter/Inputs"
uv run receipt-splitter

The 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 sync --locked --extra paddle
RECEIPT_OCR_ENGINE=paddle uv run receipt-splitter

MCP flow

Call split_receipt with an image inside the configured input folder.
Review every row and the validation report.
Call provide_assignments with row IDs mapped to names.
Call finalize_split; settle only when it reports ready: true.
Call reset after the split is complete.

Duplicate names are kept as separate rows. Fuzzy matches that are unclear remain unresolved. Tax is allocated in whole cents, so the per-person totals reconcile exactly with the receipt.

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 and RECEIPT_MAX_SESSIONS can lower those bounds.

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 build

CI runs the same checks, scans the Git history for secrets, and builds the package. See RELEASE_READINESS.md for recorded release evidence.

License

Available Tools

5 tools

finalize_splitD

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

help_receiptD

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

provide_assignmentsD

ParametersJSON Schema

Name	Required	Description	Default
`assignments`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resetD

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

split_receiptB

Validate, privately preprocess, OCR, and parse a PNG or JPEG receipt.

ParametersJSON Schema

Name	Required	Description	Default
`image_path`	Yes
`tax_included`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden; it does reveal that preprocessing is 'private' and that the tool performs a multi-stage pipeline. However, it does not disclose side effects, data persistence, error behavior, or what 'privately' concretely guarantees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the action and lists the processing stages without wasted words. Every element adds information about what the tool does.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While an output schema exists and the tool has only two parameters, the description is too thin for an agent to call it fully correctly: tax_included semantics, usage context relative to siblings, and behavioral side effects are missing. The description gives a pipeline summary but not enough operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only supports image_path by constraining the file type to PNG/JPEG. The meaning and effect of tax_included are entirely unexplained, leaving a key parameter semantically opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('Validate', 'OCR', 'parse') and identifies the resource ('PNG or JPEG receipt'), making the tool's function clear. It does not explicitly compare against siblings like finalize_split, but the processing focus is distinguishable from the sibling names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a PNG/JPEG receipt needs validation, OCR, and parsing, but it gives no explicit when-to-use or when-not-to-use guidance. Alternatives such as finalize_split or help_receipt are not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv0.2.0Sep 15, 2026
- First observedfinalize_split
- First observedhelp_receipt
- First observedprovide_assignments
- First observedreset
- First observedsplit_receipt

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.2/5.0

Scored 2026-09-15 23:55 across 5 tools

Disambiguation4/5

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.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern: reset, split_receipt, provide_assignments, finalize_split, help_receipt. Naming is predictable and uniform.

Tool Count5/5

Five tools is well-scoped for a focused receipt splitting workflow, covering reset, processing, assignment, finalization, and help without redundancy.

Completeness4/5

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

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

prismsplitOAuth
io.github.architagrawal
Split bills from your AI: read bills & balances, create equal splits, request settlements.
Finance Payments & Billing
21
money4k-split-bill B
io.github.grulex
Create a bill from a chat/photo and share it with anyone
Finance Payments & Billing
32
mrugankpednekar-bill_splitter_mcpOAuth
ai.smithery
Track and split shared expenses across trips, events, and groups. Create groups, add expenses, and…
Finance App Automation
2
ExpenseBot A
io.github.TotesMagotes
Capture receipts, scan Gmail, analyze spending, and create reviewed reports from AI assistants.
Finance Email Data Visualization
591

Related MCP Servers

Splitwise MCP Server
Finance App Automation
vishnujayvel
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage Splitwise expenses with atomic duplicate prevention, smart fuzzy matching, and support for flexible split ratios between two people.
Updated 9 months ago (2025-12-31 02:59 UTC)
MIT
kelnix-receipt-mcp-api
Finance Image & Video Processing App Automation
kelnixsolutions
A
license
Not graded
quality
B
maintenance
Turn any receipt into structured, accounting-ready JSON or clean Markdown with one API call. AI-powered vision extracts merchant, date, line items, tax, totals, and suggests GL accounts for instant bookkeeping. 50 free credits on signup.
Updated a month ago (2026-08-14 07:53 UTC)
MIT
splitwise-mcp
Finance
tarunn2799
A
license
Not graded
quality
D
maintenance
Enables natural language management of Splitwise expenses, groups, and friends via the Model Context Protocol, with dual authentication and fuzzy name resolution.
Updated 5 months ago (2026-04-26 23:04 UTC)
12
MIT
ExpensifyAI
Finance Data Visualization
udaysrinu
A
license
Not graded
quality
B
maintenance
Enables managing Splitwise expenses and generating premium spending analytics with category breakdowns, trends, and settlement optimization through natural language.
Updated 17 days ago (2026-09-03 06:31 UTC)
MIT