Docs/Troubleshooting
MCP Server

Troubleshooting

Common issues and fixes for the receiptconverter-mcp server.

Tool doesn't appear in the AI client

Symptoms
  • No receiptconverter in the tools/MCP panel
  • convert_receipt not listed
  • Server shows as disconnected
Fixes
  1. Fully restart the client — config changes only take effect on a fresh start. On macOS, quit from the menu bar, don't just close the window.
  2. Validate your JSON config at jsonlint.com — a missing comma or bracket silently prevents the server from loading.
  3. Check that Node.js 18+ is installed: run `node --version` in your terminal.
  4. Try running `npx receiptconverter-mcp` manually in your terminal. If it errors there, fix that error first.

"Unauthorized" or "Invalid API key"

Symptoms
  • Error: Invalid API key
  • HTTP 401 from the API
  • "Check RECEIPTCONVERTER_API_KEY"
Fixes
  1. Verify your key is correct in the MCP config. It should start with sk_live_ — no extra spaces, quotes, or line breaks.
  2. Make sure the env key name is exactly RECEIPTCONVERTER_API_KEY (all caps, underscore).
  3. Generate a new key from receiptconverter.com/dashboard if you think the old one was revoked.
  4. Free accounts have limited conversions. Check your usage at receiptconverter.com/dashboard.

"RECEIPTCONVERTER_API_KEY is not set"

Symptoms
  • Error message: RECEIPTCONVERTER_API_KEY is not set
Fixes
  1. The env block is missing from your config. Copy the example config block from the Quick Start page and replace only the key value.
  2. Check for typos — the key must be exactly "RECEIPTCONVERTER_API_KEY" inside the "env" object.
  3. Some clients (like Windsurf on macOS) may not inherit shell env vars. Always set the key in the config file, not as a system environment variable.

"npx not found" or "command not found"

Symptoms
  • npx: command not found
  • The system cannot find the file specified
  • spawn npx ENOENT
Fixes
  1. Install Node.js from nodejs.org. After installing, restart your computer before reopening the AI client.
  2. Use the full path to npx. Find it by running `which npx` (macOS/Linux) or `where npx` (Windows), then use that path in the args: ["args": ["/usr/local/bin/npx", "receiptconverter-mcp"]].
  3. Some AI clients launch with a minimal PATH that doesn't include Homebrew or nvm paths. Using the absolute path to npx fixes this.

"File not found" when scanning local files

Symptoms
  • Error: File not found
  • ENOENT
  • No such file or directory
Fixes
  1. Use the absolute path, not a relative path. For example: /Users/yourname/Downloads/receipt.jpg (not ./receipt.jpg).
  2. Check that the file actually exists at that path. Try opening it in Finder/Explorer first.
  3. On Windows, use forward slashes or escaped backslashes: C:/Users/name/receipt.jpg or C:\\Users\\name\\receipt.jpg.
  4. The MCP server runs as a separate process — relative paths are resolved from the server's working directory, not your project root.

Rate limit or quota errors

Symptoms
  • Error 429: Too many requests
  • "Rate limit reached"
  • Conversion quota exceeded
Fixes
  1. Check your current usage at receiptconverter.com/dashboard. Free accounts have limited conversions per month.
  2. Use the check_usage tool: ask your AI "How many receipt conversions do I have left?"
  3. Upgrade your plan at receiptconverter.com/pricing for higher limits.
  4. If batch processing, add delays between requests — the API allows up to 10 requests per minute on Pro plans.

PDF returns "scanned_pdf" error

Symptoms
  • Error: scanned_pdf
  • "This PDF appears to be a scanned image"
Fixes
  1. The API supports text-based PDFs only. Scanned PDFs (images stored as PDF) need to be converted to JPG or PNG first.
  2. On macOS, open the PDF in Preview, then export as JPEG. On Windows, use the Snipping Tool to screenshot the receipt.
  3. Alternatively, use the URL option if the receipt is accessible online — it accepts image URLs directly.

Slow responses / timeouts

Symptoms
  • Tool call takes more than 30 seconds
  • Request timed out
Fixes
  1. The MCP server has a 60-second timeout. Large PDFs or slow network connections can approach this limit.
  2. For large files, use the URL option instead of uploading — it's faster for files already hosted online.
  3. Check your internet connection. The MCP server needs to reach receiptconverter.com/api/v1/convert.

Still stuck?

Try this quick checklist:

# 1. Check Node version
node --version  # must be 18+

# 2. Test the MCP server directly
RECEIPTCONVERTER_API_KEY=sk_live_yourkey npx receiptconverter-mcp
# If it starts without error, the package works — the issue is in your client config

# 3. Validate your config JSON
# Paste it at jsonlint.com and look for syntax errors

Still need help? Email hello@receiptconverter.com with your OS, Node version, and the exact error message.

Setup guides: Claude Desktop · Cursor · Windsurf · Quick Start