MCP Server

The wiseocr-mcp package connects WiseOCR to AI assistants through the Model Context Protocol. Once it is added, you can ask Claude, Cursor or any other MCP client to turn receipts and invoices into structured JSON, or to save a whole folder of them to a CSV file.

The server runs locally on your computer, so it reads files and folders straight from your disk. Every document goes through the same API as POST /file and POST /text, and returns the same JSON.

Requirements

• A WiseOCR API key: see Create API Key
• Node.js 20 or newer

Setup

Add the server to your MCP client and put your key in place of your-api-key.

Claude Code

claude mcp add wiseocr --env WISEOCR_API_KEY=your-api-key -- npx -y wiseocr-mcp

This adds WiseOCR to the current project. Add --scope user to have it in every project.

Claude Desktop

Open Settings → Developer → Edit Config, add the wiseocr entry to claude_desktop_config.json and restart Claude Desktop.

claude_desktop_config.json

{
  "mcpServers": {
    "wiseocr": {
      "command": "npx",
      "args": ["-y", "wiseocr-mcp"],
      "env": {"WISEOCR_API_KEY": "your-api-key"}
    }
  }
}

Cursor

Add the entry to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use WiseOCR in every project.

.cursor/mcp.json

{
  "mcpServers": {
    "wiseocr": {
      "command": "npx",
      "args": ["-y", "wiseocr-mcp"],
      "env": {"WISEOCR_API_KEY": "your-api-key"}
    }
  }
}

VS Code

Add the entry to .vscode/mcp.json. VS Code asks for your API key the first time the server starts and stores it securely.

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "wiseocr-api-key",
      "description": "WiseOCR API key",
      "password": true
    }
  ],
  "servers": {
    "wiseocr": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "wiseocr-mcp"],
      "env": {"WISEOCR_API_KEY": "${input:wiseocr-api-key}"}
    }
  }
}

Other clients

Most MCP clients take the same mcpServers entry. Clients with a form need the command npx -y wiseocr-mcp and the environment variable WISEOCR_API_KEY.

{
  "mcpServers": {
    "wiseocr": {
      "command": "npx",
      "args": ["-y", "wiseocr-mcp"],
      "env": {"WISEOCR_API_KEY": "your-api-key"}
    }
  }
}

To check the connection, ask your assistant: "How many WiseOCR credits do I have left?"

Tools

Your assistant picks the right tool from what you ask.

Tool	Input	Returns
extract_receipt	source: absolute local file path or public http(s) URL	The full JSON for one receipt or invoice, with line items
extract_receipt_from_text	text: the text of one receipt or invoice	The same JSON, with no OCR step (e-mail receipts, order confirmations, pasted text)
extract_receipts_batch	paths: files and/or folders; outputFile: new .csv or .json file	A summary, with the results saved to outputFile (up to 100 documents per call)
get_account	none	The account e-mail and remaining credits (pay-as-you-go and subscription)

The three extraction tools also accept skipItems (default false). Set it to true to return only the document metadata, which makes each call faster.

Files and formats

• Images: JPG, PNG, WEBP, GIF, BMP, TIFF
• PDF files
• .txt files with receipt text
• Up to 4 MB per file

Batch output

extract_receipts_batch scans the folders you pass (subfolders are left as they are) and processes the documents three at a time. outputFile is required above 10 documents, and it must be a new file: existing files are never overwritten.

• .csv: one row per document with the columns file, status, error, documentType, time, vendor, taxNo, documentNo, country, currency, totalNet, totalTax, total and itemCount.
• .json: the full results, including line items and the tax breakdown.

Example prompts

• "Extract every receipt in ~/Documents/receipts/october and put them in a CSV with date, merchant, total and VAT."
• "Read ~/Desktop/invoice-2041.pdf and tell me the invoice number, the seller's tax ID and the total."
• "Find my taxi receipts in Gmail from last month and turn them into JSON." (with a Gmail MCP server connected)
• "How many WiseOCR credits do I have left?"

Configuration

Variable	Required	Default
WISEOCR_API_KEY	Yes	none
WISEOCR_API_URL	No	https://wiseocr.com/api/external/v1

Set WISEOCR_API_URL to point the server at another deployment, for example http://localhost:3000/api/external/v1.

Billing

Every page uses one credit from the same balance as the API. get_account is free. See pricing.

More examples and copy-ready setup for each app are on the WiseOCR MCP server page.