Suparse Document Processing MCP server

Suparse MCP Server

MCP stdio server for the Suparse Document Processing API. Use it from local MCP clients such as Claude Code and Codex to extract structured data from documents into JSON, CSV, XLSX, or Google Sheets; process single files or folders, including encrypted PDFs; let Suparse auto-detect extraction schemas or apply your team templates; create schemas automatically; split mixed multi-page documents; and download or clean up results by document ID.

Security Boundary

This is a local stdio MCP server. Connected MCP clients can ask it to read local document paths and write export files wherever the server process has permission. Only connect it to MCP clients and workspaces you trust.

Requirements

• A Suparse API key
• Node.js 20+

Authentication

The MCP server reads credentials from:

1. SUPARSEAPIKEY
2. ~/.config/suparse/config.json

You can optionally override the API base URL with SUPARSEAPIURL, or pass api_url to individual MCP tools.

Claude Code

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

Claude Desktop

Open your config file at ~/Library/Application Support/Claude/claudedesktopconfig.json on Mac or %APPDATA%\Claude\claudedesktopconfig.json on Windows. Add Suparse to the mcpServers section:

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

Codex

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

[mcp_servers.suparse]
command = "npx"
args = ["-y", "@suparse/mcp"]
tool_timeout_sec = 300

[mcp_servers.suparse.env]
SUPARSE_API_KEY = "your_api_key"

tooltimeoutsec gives Suparse extraction tools up to five minutes to finish; Codex defaults to 60 seconds.

Tools

• extractfile: Process one local document. Defaults to resultmode: "defer", returning compact taskid/documentids metadata for later downloadresults. Use resultmode: "return_json" only when the full JSON extraction is needed in the MCP response.
• extractfolder: Process supported files in one local folder. Defaults to resultmode: "defer", returning compact taskid/documentids metadata for later downloadresults. Use resultmode: "return_json" only when full JSON extractions are needed in the MCP response.
• listtemplates: List summary or full template records, grouped into directly usable teamtemplates and discovery-only system_templates.
• startquickschema_creation: Start automatic schema creation for one local document and return a normalized run ID.
• getquickschema_creation: Fetch the current automatic schema creation status for a run ID.
• waitforquickschemacreation: Poll automatic schema creation until it reaches a terminal result.
• fetchjsonresults: Fetch JSON extraction results by document ID directly in the MCP response. Use only when full JSON is needed in context.
• fetchdocumentresult: Fetch one document's structured JSON result through the direct single-document endpoint.
• downloadresults: Fetch an export by document ID and write it directly to local disk. Use this for json, csv, xlsx, and googlesheets.
• delete_documents: Delete documents by ID.

Export Formats

fetchjsonresults accepts:

JSON exports are returned as structured results.

Shortened. The full README is on GitHub.