Use Suparse with Your AI Assistant

Connect Suparse to your AI assistant to extract data from documents using everyday prompts.

Use Claude Code, Claude Desktop, Codex, Cursor, VS Code with GitHub Copilot, Copilot CLI, Gemini CLI, or Windsurf/Cascade to process invoices, receipts, bank statements, and other supported documents. Your assistant handles uploading, checking progress, and saving results for you.

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.
• Save results as JSON, CSV, or Excel, or export to Google Sheets.
• Delete processed documents from Suparse when you are done.

Requirements

• Node.js 20 or newer
• A Suparse API key
• One of the supported assistants installed on your computer

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.

Replace your_api_key in the setup examples with your Suparse API key. Keep it private: do not share configuration files containing a real key or commit them to Git. Terminal commands containing your key may remain in shell history.

Suparse MCP runs on your computer and uploads the documents you ask it to process to Suparse. Connect it only to assistants and projects you trust. Processing may consume Suparse credits.

Choose Your Assistant

Follow just the section for your assistant:

• Claude Code
• Claude Desktop
• Codex
• Cursor
• VS Code / GitHub Copilot
• Copilot CLI
• Gemini CLI
• Windsurf / Cascade

If a configuration file already contains other servers, add Suparse alongside them rather than replacing the file.

Install in Claude Code

Run this command in your terminal:

claude mcp add --scope user suparse --env SUPARSE_API_KEY=your_api_key -- npx -y @suparse/mcp

This makes Suparse available across your projects. Restart Claude Code and use /mcp to check the connection. Then verify your setup.

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, then verify your setup.

If Windows cannot start npx, change "command": "npx" to "command": "cmd" and change args to ["/c", "npx", "-y", "@suparse/mcp"].

Install in Codex

Run this in your terminal:

codex mcp add suparse --env SUPARSE_API_KEY=your_api_key -- npx -y @suparse/mcp

Then open ~/.codex/config.toml and add this line inside the existing [mcp_servers.suparse] section, above any following section:

tool_timeout_sec = 300

This gives document processing up to five minutes. Restart Codex and use /mcp to check the connection, then verify your setup. The same settings work with the Codex IDE extension.

Install in Cursor

Open ~/.cursor/mcp.json for all projects, or .cursor/mcp.json inside one project, and add:

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

Keep this file private if it contains your key. Open Cursor's MCP settings, enable Suparse, then verify your setup in Agent chat.

Install in VS Code / GitHub Copilot

For VS Code, create .vscode/mcp.json in your project and add:

{
  "inputs": [
    {
      "id": "suparse-api-key",
      "type": "promptString",
      "description": "Suparse API key",
      "password": true
    }
  ],
  "servers": {
    "suparse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "${input:suparse-api-key}"
      }
    }
  }
}

Open the Command Palette and run MCP: List Servers. Select Suparse and start it. Enter your API key when prompted; the key stays out of the JSON file. Then verify your setup in agent chat.

Install in Copilot CLI

Run:

copilot mcp add suparse --env SUPARSE_API_KEY=your_api_key --timeout 300000 -- npx -y @suparse/mcp
copilot mcp list

The timeout gives document processing up to five minutes. Then verify your setup in Copilot CLI.

Install in Gemini CLI

Run:

gemini mcp add --scope user --env SUPARSE_API_KEY=your_api_key suparse npx -y @suparse/mcp
gemini mcp list

This installs Suparse for your user account. Then verify your setup in Gemini CLI.

Install in Windsurf / Cascade

These steps are for the legacy Cascade agent. If you use the newer Devin Local agent, follow its MCP setup instructions.

Open the MCP configuration file from Cascade's MCP controls. Add the same JSON shown in the Claude Desktop setup, using your API key.

Save the file, refresh the MCP list or restart the app, and enable Suparse in Cascade. Then verify your setup.

Check Your Connection

Ask your assistant:

Use Suparse to list my available extraction templates.

Approve the tool call if prompted. A successful response means the connection and API key work. An empty template list is fine if you have not added any templates. This check does not upload or process documents.

To try document processing, use a small sample PDF:

Use Suparse to extract /full/path/to/sample.pdf. Show me the result and keep the uploaded document in Suparse.

Processing this sample may consume credits.

Use the Right File Path

Use the full path to a file or folder your assistant can access. For example, use /Users/you/Documents/invoice.pdf on macOS or C:\Users\you\Documents\invoice.pdf on Windows. If your assistant runs inside WSL, use its Linux path, such as /mnt/c/Users/you/Documents/invoice.pdf.

Short paths such as ./invoice.pdf depend on where the assistant starts Suparse. Use a full path if the assistant cannot find a file. Replace paths in the example prompts below with your own.

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: /full/path/to/invoice.pdf

Process the PDFs directly inside /full/path/to/vendor-invoices and save the results as XLSX.

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

Extract /full/path/to/receipts/january.pdf and save the CSV to /full/path/to/exports.

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:

Connect Google Sheets in Suparse before asking for a Sheets export. The assistant returns spreadsheet links and can save those links as a metadata file; it does not download an Excel file. Only immediate Sheets exports are supported. To choose an existing spreadsheet or append rows, use the Suparse interface.

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

Your documents are uploaded to Suparse for processing. Deletion removes them from Suparse, not just from a temporary folder on your computer. If you want documents removed after processing, say so explicitly:

Extract /full/path/to/invoice.pdf with Suparse, download the result as XLSX, and delete the processed document from Suparse 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.

If a request times out, ask the assistant to check the existing task or retrieve its results before uploading the same file again.

For advanced options, see the full MCP documentation.