# ScanToBill MCP Server

<p align="center">
  <a href="https://www.npmjs.com/package/@scantobill/mcp-server"><img src="https://img.shields.io/npm/v/@scantobill/mcp-server?color=6366F1&labelColor=1e1e2e&label=npm" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@scantobill/mcp-server"><img src="https://img.shields.io/npm/dm/@scantobill/mcp-server?color=6366F1&labelColor=1e1e2e" alt="downloads" /></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-6366F1?labelColor=1e1e2e" alt="Node.js" /></a>
  <img src="https://img.shields.io/badge/license-MIT-6366F1?labelColor=1e1e2e" alt="MIT" />
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-6366F1?labelColor=1e1e2e" alt="MCP" /></a>
  <a href="https://smithery.ai/servers/scantobill/mcp-server"><img src="https://smithery.ai/badge/scantobill/mcp-server" alt="Smithery" /></a>
</p>

<p align="center"><strong>Extract structured JSON from invoices and business documents — inside Claude Desktop.</strong></p>

<p align="center">
  <a href="https://app.scantobill.com/keys">Get a free API key →</a> ·
  <a href="https://app.scantobill.com/docs">Docs</a> ·
  <a href="https://www.npmjs.com/package/@scantobill/mcp-server">npm</a> ·
  <a href="https://nooot77.github.io/scantobill-mcp-server/">Landing page</a>
</p>

---

## What is this?

ScanToBill is an AI-powered OCR platform for **Arabic and English business documents** — invoices, receipts, contracts, and IDs. This package connects ScanToBill to **Claude Desktop** (or any MCP-compatible AI client) so you can extract invoice data just by sharing a URL with Claude.

```
You: "Extract the line items from this invoice: https://example.com/invoice.pdf"

Claude: Here's what I found:
  - Consulting services: SAR 5,000
  - VAT (15%): SAR 750
  - Total: SAR 5,750

  Vendor: Al-Noor Trading Co.
  Date: 2026-07-15
  Invoice #: INV-2026-0042
```

---

## Quick start

```bash
npx @scantobill/mcp-server --api-key ocr_sk_YOUR_KEY
```

Get a free API key at [app.scantobill.com/keys](https://app.scantobill.com/keys) — 20 extractions/month, no credit card.

---

## Claude Desktop setup

**1. Open the config file**

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

**2. Add this entry**

```json
{
  "mcpServers": {
    "scantobill": {
      "command": "npx",
      "args": ["-y", "@scantobill/mcp-server", "--api-key", "ocr_sk_YOUR_KEY"]
    }
  }
}
```

**3. Restart Claude Desktop** — done.

---

## Available tools

| Tool | Description |
|------|-------------|
| `extract_document` | Extract structured JSON from an invoice, receipt, or business document at a public URL |
| `list_extractions` | List past extractions with optional date, type, and status filters |
| `get_extraction` | Fetch full metadata for a specific extraction by ID |

### `extract_document`
```
url            (required) Public URL — PDF, JPG, PNG, or TIFF
document_type  invoice · receipt · contract · id  (default: invoice)
language       ar · en · auto  (default: auto)
```

### `list_extractions`
```
limit    Number of results (default: 10, max: 50)
status   pending · processing · done · failed
from     ISO 8601 start date
to       ISO 8601 end date
```

### `get_extraction`
```
id    (required) Extraction ID returned by extract_document
```

---

## Authentication

```bash
# CLI flag
npx @scantobill/mcp-server --api-key ocr_sk_YOUR_KEY

# Environment variable
SCANTOBILL_API_KEY=ocr_sk_YOUR_KEY npx @scantobill/mcp-server
```

---

## Supported documents

| Type | Arabic | English | Mixed |
|------|:------:|:-------:|:-----:|
| Invoice (فاتورة) | ✅ | ✅ | ✅ |
| Receipt (إيصال) | ✅ | ✅ | ✅ |
| Contract (عقد) | ✅ | ✅ | ✅ |
| National ID | ✅ | ✅ | — |
| VAT invoice (ZATCA) | ✅ | — | — |

---

## Pricing

| Plan | Extractions/month | Price |
|------|:----------------:|-------|
| Free | 20 | $0 |
| Starter | 500 | $15 |
| Pro | 5,000 | $49 |
| Enterprise | Unlimited | Custom |

---

## License

MIT © [ScanToBill](https://app.scantobill.com)