🧾 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

📧 Contact: [email protected] | 🔗 kelnix.org

---

⚡ Quickstart

1️⃣ Register (instant, no approval)

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)

curl -X POST https://receipt-mcp-api.kelnix.org/tools/upload_and_process \
  -H "X-API-Key: rct_your-key-here" \
  -F "[email protected]" \
  -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

# 💳 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 (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:

{
  "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:

{
  "mcpServers": {
    "kelnix-receipt": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Also discoverable via /.well-known/mcp.json and listed on Smithery.ai.

---

🧩 Framework Integrations

GET /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.

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

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}