The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Suparse Document Processing listing page.
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; let Suparse auto-detect extraction schemas or apply your team templates; split mixed multi-page documents; and download or clean up results by document ID.
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.
The MCP server reads credentials from:
SUPARSE_API_KEY~/.config/suparse/config.jsonYou can optionally override the API base URL with SUPARSE_API_URL, or pass api_url to individual MCP tools.
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:
Add this to ~/.codex/config.toml or a project-scoped .codex/config.toml:
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 metadata for templates, grouped into directly usable team_templates and discovery-only system_templates.fetch_json_results: Fetch JSON extraction results by document ID directly in the MCP response. Use only when full JSON is needed in context.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.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. 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.
MCP agents should use only team_templates when passing template_id to extract_file or extract_folder.
When a user asks to process a document type such as a receipt:
team_templates first and use the matching team template if present.list_templates with include_system: true and check system_templates.Build the package:
Test with MCP Inspector:
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.