๐งพ Kelnix Receipt MCP API
> Turn any receipt into structured, accounting-ready JSON with one API call. AI vision extracts everything โ merchant, date, line items, tax, totals โ and suggests GL accounts for instant bookkeeping.
Built for AI agents that automate expense management, accounts payable, and bookkeeping. No dashboard, no login โ just an API that speaks MCP.
๐ **50 free credits on signup. No credit card required.**
๐ **Live at** `receipt-mcp-api.kelnix.org` โ [Interactive Docs](https://receipt-mcp-api.kelnix.org/docs)
๐ง **Contact:** info@kelnix.org | ๐ [kelnix.org](https://kelnix.org)
---
## โก Quickstart
### 1๏ธโฃ Register (instant, no approval)
```bash
curl -X POST https://receipt-mcp-api.kelnix.org/register_agent \
-H "Content-Type: application/json" \
-d '{"agent_name": "my-expense-bot"}'
```
โ
Returns your API key + 50 free credits.
### 2๏ธโฃ Process a receipt (1 credit)
```bash
curl -X POST https://receipt-mcp-api.kelnix.org/tools/upload_and_process \
-H "X-API-Key: rct_your-key-here" \
-F "file=@receipt.jpg" \
-F "mime_type=image/jpeg"
```
โ
Returns structured JSON: vendor, date, line items, totals, tax, currency, confidence scores.
### 3๏ธโฃ Buy more credits when you need them
```bash
# ๐ณ With card (Stripe)
curl -X POST https://receipt-mcp-api.kelnix.org/billing/buy_credits \
-H "X-API-Key: rct_your-key-here" \
-H "Content-Type: application/json" \
-d '{"credits": 1000}'
# ๐ช With crypto (300+ coins)
curl -X POST https://receipt-mcp-api.kelnix.org/billing/buy_credits_crypto \
-H "X-API-Key: rct_your-key-here" \
-H "Content-Type: application/json" \
-d '{"credits": 1000, "preferred_coin": "eth"}'
```
---
## ๐ฐ Pricing
### Credit Packs
| Credits | Price | Per credit |
|---------|-------|-----------|
| 100 | $5 | $0.050 |
| 500 | $20 | $0.040 |
| 1,000 | $40 | $0.040 |
| 5,000 | $150 | $0.030 |
| 10,000 | $300 | $0.030 |
### ๐
Subscriptions
| Plan | Credits/mo | Price |
|------|-----------|-------|
| ๐ Free | 50 (signup) | $0 |
| โญ Basic | 200/mo | $15/mo |
| ๐ Pro | 2,000/mo | $99/mo |
### ๐ง Tool Costs
| Tool | Cost |
|------|------|
| `receipts.process` | 1 credit |
| `receipts.upload_and_process` | 1 credit |
| `accounting.suggest_gl_account` | 1 credit |
| `receipts.upload` | ๐ Free |
| `receipts.get_markdown` | ๐ Free |
| `credits.check_balance` | ๐ Free |
| `receipts.list` | ๐ Free |
Full pricing also available at [`GET /pricing`](https://receipt-mcp-api.kelnix.org/pricing) (no auth required).
---
## ๐ API Reference
### ๐ง Tools
| Method | Endpoint | Cost | Description |
|--------|----------|------|-------------|
| POST | `/tools/upload_receipt` | Free | Upload receipt image/PDF |
| POST | `/tools/process_receipt` | 1 credit | Extract structured data |
| POST | `/tools/upload_and_process` | 1 credit | Upload + process in one call (idempotent) |
| POST | `/tools/get_receipt_markdown` | Free | Get processed receipt as Markdown |
| POST | `/tools/suggest_gl_account` | 1 credit | AI-suggest GL account code |
| POST | `/tools/check_balance` | Free | Check credits and plan |
| POST | `/tools/list_receipts` | Free | List receipts with filters |
| POST | `/tools/process_receipt_async` | 1 credit | Queue async processing (requires Redis) |
### ๐ณ Billing
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/billing/buy_credits` | Buy credit pack (Stripe Checkout) |
| POST | `/billing/subscribe` | Subscribe to monthly plan |
| POST | `/billing/buy_credits_crypto` | Buy credits with 300+ cryptocurrencies |
| POST | `/billing/check_payment_status` | Check crypto payment status |
| GET | `/billing/balance` | Full balance with transaction history |
### ๐ก Discovery & Info
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/mcp` | Tool catalogue with schemas, examples, constraints |
| GET | `/.well-known/mcp.json` | MCP server discovery metadata |
| GET | `/pricing` | Public pricing (no auth) |
| GET | `/legal/terms` | Terms of Service |
| GET | `/legal/privacy` | Privacy Policy |
| GET | `/integrations` | Code snippets for LangGraph, CrewAI, AutoGen |
| GET | `/docs` | Interactive Swagger documentation |
| GET | `/health` | Health check |
### ๐ Authentication
All tool and billing endpoints require the `X-API-Key` header. Get a key via `POST /register_agent`.
When you run out of credits, paid endpoints return `402` with links to buy more:
```json
{
"error": "Insufficient credits: 0 available, 1 required.",
"buy_credits_url": "/billing/buy_credits",
"buy_credits_crypto_url": "/billing/buy_credits_crypto",
"pricing_url": "/pricing",
"cheapest_option": "100 credits for $5.00"
}
```
---
## ๐ MCP Protocol
Works with Claude Desktop, Cursor, and any MCP-compatible client:
```json
{
"mcpServers": {
"kelnix-receipt": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}
}
}
```
Also discoverable via [`/.well-known/mcp.json`](https://receipt-mcp-api.kelnix.org/.well-known/mcp.json) and listed on [Smithery.ai](https://smithery.ai).
---
## ๐งฉ Framework Integrations
[`GET /integrations`](https://receipt-mcp-api.kelnix.org/integrations) returns ready-to-use code for:
| Framework | Integration |
|-----------|-------------|
| ๐ฆ **LangGraph** | Tool node integration |
| ๐ข **CrewAI** | BaseTool subclass |
| ๐ค **AutoGen** | Registered function |
| ๐ **Raw Python** | Full flow with httpx |
See `examples/` directory for complete implementations.
---
## ๐ช Crypto Payments
Pay with **BTC, ETH, SOL, USDC, USDT, DOGE**, and 280+ more coins. Credits priced in USD, crypto amount locked at current rate for ~20 minutes.
```bash
curl -X POST https://receipt-mcp-api.kelnix.org/billing/buy_credits_crypto \
-H "X-API-Key: rct_your-key-here" \
-H "Content-Type: application/json" \
-d '{"credits": 1000, "preferred_coin": "btc"}'
```
Returns payment address and exact amount. Credits granted automatically on confirmation.
---
## ๐ ๏ธ Self-Hosting
```bash
git clone https://github.com/kelnixsolutions/Kelnix-Receipt-MCP-API.git
cd Receipt-Accounting-Entry-MCP-Server
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
uvicorn app:app --host 0.0.0.0 --port 8000
```
Requires Python 3.11+. See `deploy/setup.sh` for production deployment with nginx, SSL, and systemd.
| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | โ
Yes | Anthropic API key for Claude vision |
| `STRIPE_SECRET_KEY` | โ No | Stripe secret key for billing |
| `STRIPE_WEBHOOK_SECRET` | โ No | Stripe webhook signing secret |
| `NOWPAYMENTS_API_KEY` | โ No | NOWPayments API key for crypto |
| `REDIS_URL` | โ No | Redis URL for async processing |
---
## ๐ License
MIT
---
Built with โค๏ธ by Kelnix
Powering the next generation of AI expense agents