Docs/Windsurf
MCP Server

Windsurf Setup

Add receipt and invoice parsing to Windsurf's Cascade agent. One config block and a restart is all it takes.

Time to complete: ~2 minutes  ·  Requires: Windsurf, Node.js 18+, ReceiptConverter API key

Config file location

Windsurf stores MCP config in:

macOS / Linux
~/.codeium/windsurf/mcp_config.json
Windows
%USERPROFILE%\.codeium\windsurf\mcp_config.json

You can also open it from Windsurf: Windsurf → Settings → Cascade → MCP Servers → Open Config.

Add the server

Get your API key from receiptconverter.com/dashboard, then add this block:

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

Verify and use

Restart Windsurf. In the Cascade panel, click Configure MCP — you should see receiptconverter with a green status indicator.

Switch to Write mode (the mode that can call tools) and try:

“Parse this receipt URL and return the JSON data”
“Scan /path/to/receipt.jpg and extract the total and line items”
“Check how many API calls I have remaining”

Troubleshooting

Server not appearing after restart
Check the mcp_config.json for JSON syntax errors (missing commas, brackets). A typo silently prevents loading.
npx command not found
Windsurf may not inherit your shell PATH. Try using the full path to npx: run `which npx` in your terminal and use that absolute path in the args.
Tool only available in Write mode
Cascade's tool-calling is only available in Write mode, not in Chat-only mode. Switch modes using the toggle in the Cascade panel.