Use Suparse with Claude and Codex

The Suparse MCP server lets AI coding assistants process local documents through the Suparse Document Processing API.

After setup, you can ask Claude Code, Claude Desktop, or Codex to extract structured data from invoices, receipts, bank statements, purchase orders, and other supported documents without writing upload or polling code yourself.

What You Can Do

• Extract one local PDF or image file.
• Extract every supported document in a local folder.
• List the extraction templates available to your account.
• Download results as JSON, CSV, XLSX, or Google Sheets.
• Delete processed documents from Suparse when you are done.

Requirements

• Node.js 20 or newer
• A Suparse API key
• Claude Code, Claude Desktop, Codex, or another MCP-compatible local client

To create an API key:

1. Sign in at suparse.com
2. Open the API Keys tab
3. Click Generate New Key
4. Copy the key value. It is shown only once.

Install in Claude Code

Run this command in your terminal:

claude mcp add suparse -e SUPARSE_API_KEY=your_api_key -- npx -y @suparse/mcp

Replace your_api_key with your Suparse API key.

Then restart Claude Code, or reload its MCP configuration if your environment supports reloads.

Try it with a prompt like:

Extract data from ./invoices/acme-invoice.pdf with Suparse and save the result as CSV.

Install in Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add Suparse to the mcpServers section:

{
  "mcpServers": {
    "suparse": {
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "your_api_key"
      }
    }
  }
}

If your config file already has other MCP servers, add only the suparse entry inside the existing mcpServers object.

Restart Claude Desktop after saving the file.

Try it with a prompt like:

Use Suparse to extract the receipts in ~/Documents/receipts and download the results as an Excel file.

Install in Codex

Add this to ~/.codex/config.toml, or to a project-scoped .codex/config.toml:

[mcp_servers.suparse]
command = "npx"
args = ["-y", "@suparse/mcp"]
 
[mcp_servers.suparse.env]
SUPARSE_API_KEY = "your_api_key"

Replace your_api_key with your Suparse API key, then restart Codex or reload MCP configuration.

Try it with a prompt like:

Use Suparse MCP to extract ./statements/may.pdf and download unified JSON to ./exports.

How to Ask Your Assistant

You do not need to call MCP tools by name in normal use. Ask for the document task you want completed:

Extract this invoice with Suparse and show me the totals and line items: ./invoice.pdf

Process all PDFs in ./vendor-invoices and save the results as XLSX.

List my Suparse templates and tell me which one looks right for bank statements.

Extract ./receipts/january.pdf, save CSV output to ./exports, then delete the processed document from Suparse.

For large documents or folders, ask the assistant to download the results to disk instead of putting the full JSON response into chat.

Result Downloads

Suparse MCP supports these result formats:

The recommended workflow is:

1. Ask the assistant to extract the file or folder.
2. Ask it to download results in the format you need.
3. Ask it to delete processed documents from Suparse if you no longer need them stored.

This keeps chat responses compact and avoids filling your assistant context with large JSON payloads.

Privacy and Cleanup

If you want documents removed after processing, say so explicitly:

Extract ./invoice.pdf with Suparse, download the result as XLSX, and delete the processed document afterward.

For CSV, XLSX, Google Sheets, or saved JSON files, the assistant should first download the result and then delete the document.

Avoid asking for automatic cleanup before export download, because deleted document IDs cannot be used for later exports.

Troubleshooting

If Suparse tools do not appear in your assistant, restart the client after editing the MCP configuration.

If the server cannot authenticate, confirm that the API key was copied correctly and is set as SUPARSE_API_KEY.

If npx is not found, install Node.js 20 or newer and reopen your terminal or desktop app.

If extraction works but exports are missing, ask your assistant to download results by document_id using the format you want.