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. SUPARSE_API_KEY
2. ~/.config/suparse/config.json

You can optionally override the API base URL with SUPARSE_API_URL, 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/claude_desktop_config.json on Mac or %APPDATA%\Claude\claude_desktop_config.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"

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

Tools

• extract_file: Process one local document. Defaults to result_mode: "defer", returning compact task_id/document_ids metadata for later download_results. Use result_mode: "return_json" only when the full JSON extraction is needed in the MCP response.
• extract_folder: Process supported files in one local folder. Defaults to result_mode: "defer", returning compact task_id/document_ids metadata for later download_results. Use result_mode: "return_json" only when full JSON extractions are needed in the MCP response.
• list_templates: List summary or full template records, grouped into directly usable team_templates and discovery-only system_templates.
• start_quick_schema_creation: Start automatic schema creation for one local document and return a normalized run ID.
• get_quick_schema_creation: Fetch the current automatic schema creation status for a run ID.
• wait_for_quick_schema_creation: Poll automatic schema creation until it reaches a terminal result.
• fetch_json_results: Fetch JSON extraction results by document ID directly in the MCP response. Use only when full JSON is needed in context.
• fetch_document_result: Fetch one document's structured JSON result through the direct single-document endpoint.
• download_results: Fetch an export by document ID and write it directly to local disk. Use this for json, csv, xlsx, and google_sheets.
• delete_documents: Delete documents by ID.

Export Formats

fetch_json_results accepts:

| Input | Values | Default | | ------------- | --------------------- | --------- | | export_type | original, unified | unified |

JSON exports are returned as structured results.

download_results accepts json, csv, xlsx, and google_sheets, plus an optional output_path local file path or existing directory. XLSX exports additionally accept xlsx_layout: "standard" | "flat" and default to standard. It writes the export directly to disk and returns the saved output_path. MCP clients should use download_results for CSV, XLSX, Google Sheets, and saved JSON files; they should not fetch base64 data and decode it with shell or Python.

result_mode controls whether extraction results in JSON format are returned directly. Use return_json only when you need the full JSON extraction in the MCP response. In all other cases you can retrieve the results in the format of your choice using download_results.

Important: cleanup on extract_file and extract_folder is only valid with result_mode: "return_json". It fetches JSON and then deletes the processed Suparse documents, so later exports cannot be fetched from those document IDs. For CSV/XLSX/Google Sheets or saved JSON files, run extract_file or extract_folder with result_mode: "defer", call download_results, then call delete_documents.

extract_file and extract_folder accept an optional pdf_password for encrypted PDFs and folder_id for assigning uploads to a remote Suparse folder. Treat pdf_password as a secret and do not include it in prompts, logs, or saved tool arguments.

Automatic Schema Creation

Call start_quick_schema_creation with a local file, then pass its normalized run_id to get_quick_schema_creation or wait_for_quick_schema_creation. Terminal results preserve generated template IDs, saved documents, failed-document details, and retryability. The start tool also accepts pdf_password and folder_id.

upload_batch_id and source_upload_id are supported only for advanced workflows that obtain those IDs elsewhere; the MCP server does not create upload batches.

Template Selection for MCP Agents

MCP agents should use only team_templates when passing template_id to extract_file or extract_folder. Use the default summary view for normal selection and request view: "full" only when schema, prompt, validation, or creator metadata is needed.

When a user asks to process a document type such as a receipt:

1. Check team_templates first and use the matching team template if present.
2. If no matching team template exists, call list_templates with include_system: true and check system_templates.
3. If a matching system template exists, ask the user to add that system template to their templates in the Suparse UI before processing. Do not pass the system template ID directly to extraction.
4. If no matching team or system template exists, ask the user to create a custom extraction schema for that document type in the Suparse UI.

Development

Build the package:

pnpm build

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.mjs

The MCP server uses stdout for JSON-RPC protocol messages. Do not add console.log output to the server path; use stderr or MCP tool responses.