# receiptconverter-mcp

> MCP server for [ReceiptConverter](https://receiptconverter.com) — parse any receipt or invoice into structured JSON with a single tool call.

Connects Claude Desktop, Cursor, Windsurf, and any [Model Context Protocol](https://modelcontextprotocol.io) client directly to the ReceiptConverter API. No HTTP setup required — just drop in your API key and your AI assistant can scan receipts natively.

## Quick start

### 1. Get an API key

Sign in at [receiptconverter.com](https://receiptconverter.com), open **Dashboard → API Keys**, and generate a key.

### 2. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "receiptconverter": {
      "command": "npx",
      "args": ["receiptconverter-mcp"],
      "env": {
        "RECEIPTCONVERTER_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

Restart Claude. You'll see `receiptconverter` appear in the tools panel.

### 3. Add to Cursor

Open **Cursor Settings → MCP** and add:

```json
{
  "receiptconverter": {
    "command": "npx",
    "args": ["receiptconverter-mcp"],
    "env": {
      "RECEIPTCONVERTER_API_KEY": "sk_live_your_key_here"
    }
  }
}
```

## Tools

### `convert_receipt`

Parse a receipt or invoice image/PDF into structured JSON.

| Parameter | Type | Description |
|---|---|---|
| `url` | string | Public URL of a receipt image or PDF |
| `file_path` | string | Absolute path to a local file |
| `file_name` | string | Optional filename hint |

One of `url` or `file_path` is required.

**Supported formats:** JPG, PNG, WEBP, HEIC, TIFF, BMP, PDF (text-based)

**Returns:**
```json
{
  "vendor": "Starbucks",
  "date": "2024-03-15",
  "total": 12.50,
  "subtotal": 11.00,
  "tip": 1.50,
  "currency": "USD",
  "payment_method": "Visa",
  "category": "Food & Drink",
  "taxes": [{ "label": "Sales Tax", "rate": 8.875, "amount": 0.98 }],
  "items": [
    { "name": "Oat Latte", "quantity": 1, "unit_price": 6.50, "total_price": 6.50 },
    { "name": "Croissant",  "quantity": 1, "unit_price": 4.50, "total_price": 4.50 }
  ]
}
```

**Example prompts:**
- *"Parse the receipt at https://example.com/receipt.jpg"*
- *"Convert /Users/me/Downloads/expense.pdf to JSON"*
- *"Extract all line items from this receipt and add them to my expense spreadsheet"*

---

### `check_usage`

Check your remaining conversions for the current billing period.

No parameters required.

---

## Example — Claude workflow

```
You: Parse this receipt and add the total to my expenses spreadsheet
     [attaches receipt.jpg]

Claude: I'll use the convert_receipt tool to parse this.

        Vendor:    Whole Foods Market
        Date:      2024-03-20
        Total:     USD 47.83
        Items (6): Organic Milk × 1 @ $5.99 ...
        Category:  Groceries

        I've extracted 6 line items. Want me to format these for your spreadsheet?
```

## Pricing

The MCP server uses your ReceiptConverter API key. See [receiptconverter.com/pricing](https://receiptconverter.com/pricing) for plan details.

- Free tier: limited conversions/month
- Pro plan: 100 conversions/month
- API plan: higher limits

## Links

- [API Docs](https://receiptconverter.com/docs/api)
- [Quickstart](https://receiptconverter.com/docs/quickstart)
- [MCP Integration Guide](https://receiptconverter.com/docs/guides/mcp-ai-agents)
- [Dashboard](https://receiptconverter.com/dashboard)

## License

MIT