Extract structured data from PDFs and documents into JSON, CSV, or Excel using AI-powered OCR and automated schema detection.
Also known as suparse/suparse-mcp, suparse-mcp, @suparse/mcp
- Stars
- 0
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- 1.5.0
- Last commit
- Oct 19, 2026
- License
- MIT
What is Suparse MCP?
Suparse extracts structured data from PDFs and documents into JSON, CSV, or Excel using AI-powered OCR and automated schema detection. It exposes 17 tools, such as extract_file, extract_folder, start_file_extraction.
Summary generated from the project's README
About Suparse MCP server
Extracting structured data from PDFs and other documents into organized formats is what Suparse Document Processing enables for developers using AI-powered clients. By connecting this local stdio server to tools like Claude Code, Cursor, or VS Code, you can transform unstructured files into JSON, CSV, XLSX, or Google Sheets. The server handles complex tasks such as processing encrypted PDFs, splitting mixed multi-page documents, and automatically detecting extraction schemas or applying specific team templates.
To use this server, you must provide a Suparse API key via environment variables or a local configuration file. It runs as a local process, meaning it can read files from your local paths and write exported results directly to your machine. It is designed to work with various MCP-compatible environments including Claude Desktop, Codex, Gemini CLI, and Windsurf. The system supports both single file extractions and bulk folder processing to streamline large data entry workflows.
What you can do with it
- 1Automated schema applicationYou can use predefined team templates to ensure document data is extracted according to specific organizational requirements.
Written from the project's README. Every use case is checked against a quote from it.
How to install Suparse MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Suparse MCP in Claude Code
$ claude mcp add --env 'SUPARSE_API_KEY=<YOUR_SUPARSE_API_KEY>' suparse-mcp -- npx -y @suparse/mcpInstall Suparse MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"suparse-mcp": {
"command": "npx",
"args": [
"-y",
"@suparse/mcp"
],
"env": {
"SUPARSE_API_KEY": "<YOUR_SUPARSE_API_KEY>"
}
}
}
}Install Suparse MCP in VS Code
.vscode/mcp.json
{
"servers": {
"suparse-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@suparse/mcp"
],
"env": {
"SUPARSE_API_KEY": "<YOUR_SUPARSE_API_KEY>"
}
}
}
}Install Suparse MCP in VS Code CLI
$ code --add-mcp '{"name":"suparse-mcp","type":"stdio","command":"npx","args":["-y","@suparse/mcp"],"env":{"SUPARSE_API_KEY":"<YOUR_SUPARSE_API_KEY>"}}'Install Suparse MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"suparse-mcp": {
"command": "npx",
"args": [
"-y",
"@suparse/mcp"
],
"env": {
"SUPARSE_API_KEY": "<YOUR_SUPARSE_API_KEY>"
}
}
}
}Install Suparse MCP in Codex
$ codex mcp add suparse-mcp --env 'SUPARSE_API_KEY=<YOUR_SUPARSE_API_KEY>' -- npx -y @suparse/mcpInstall Suparse MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.suparse-mcp] command = "npx" args = ["-y", "@suparse/mcp"] [mcp_servers.suparse-mcp.env] SUPARSE_API_KEY = "<YOUR_SUPARSE_API_KEY>"
Install Suparse MCP in Gemini CLI
$ gemini mcp add -s user -e 'SUPARSE_API_KEY=<YOUR_SUPARSE_API_KEY>' suparse-mcp npx -- -y @suparse/mcpInstall Suparse MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"suparse-mcp": {
"command": "npx",
"args": [
"-y",
"@suparse/mcp"
],
"env": {
"SUPARSE_API_KEY": "<YOUR_SUPARSE_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @suparse/mcp 1.5.0 in an isolated container with no network and no keys. It answered and listed 17 tools.
Suparse MCP tools 17
Read from the server with tools/listextract_fileActionProcess one local file through Suparse. Defaults to result_mode defer: upload, wait for terminal processing, and return task_id/document_ids for later export. A partially_completed task retains its status. For an immediate task ID, use start_file_extraction, then wait_for_task_extraction and get_task_results. auto_approve defaults true; false requests human review, and this combined tool may wait and time out while review is pending. return_json preserves per-input task status and document IDs, reports partial tasks and empty exports as incomplete, and preserves exported data. cleanup is best-effort, allowed only with return_json, and requires a completed task and an export covering every requested document.
extract_folderActionProcess sorted, immediate supported files in a local folder through Suparse (nonrecursive; directories are skipped). Defaults to result_mode defer: upload and wait for each task, retaining task status and document IDs. For task IDs before processing finishes, use start_folder_extraction. At most 10 files run concurrently. auto_approve defaults true; false requests human review, and this combined tool may wait and time out while review is pending. return_json preserves per-input task status and document IDs, reports partial tasks and empty exports as incomplete, and preserves exported data. cleanup is best-effort, allowed only with return_json, and requires a completed task and an export covering every requested document.
start_file_extractionActionStart background extraction of one local file; return task_id after upload confirmation without waiting for processing or exporting results. This confirms submission, not successful extraction. Use wait_for_task_extraction, then fetch_document_result for a returned document ID or download_results to save an export; get_task_results can inspect partial documents. Uploads may consume credits. On timeout, use any returned recovery task_id rather than uploading again. auto_approve defaults true; false requests human review, which MCP cannot perform or approve. The returned auto_approve echoes the requested option, not backend approval status.
start_folder_extractionActionStart background extraction of sorted supported files directly inside a local folder, skipping directories and subfolders. Returns one task_id per confirmed upload without waiting for processing or exporting. At most 10 uploads run concurrently. Use wait_for_task_extraction for each task, then fetch or download results using its document IDs. Uploads may consume credits. Inspect failed entries and recovery IDs before retrying; cancellation prevents new uploads, but submitted tasks may still run. Entries marked unstarted were not uploaded. auto_approve defaults true; false requests human review, which MCP cannot perform or approve.
wait_for_task_extractionRead-onlyWait for an existing extraction task_id; returns status and document_ids, not extracted data. completed and partially_completed return successfully; failed and insufficient_credits produce errors. Partial completion is not success for every document. Use fetch_document_result or download_results with the returned document IDs. Defaults to poll_interval 2 seconds and max_poll_attempts 3; SDK backoff and retries mean this is not a strict wall-clock deadline. On polling timeout, call again with the same task_id rather than uploading again. This does not approve documents awaiting human review.
list_templatesRead-onlyDiscover extraction templates; defaults to compact summary view with team templates only. Prefer a matching active team template and pass its id as template_id to extraction tools. Use view full to inspect schema and prompts. include_system true adds discovery-only system templates; MCP cannot add them to the team or use their IDs directly. If no template matches, omit template_id for auto-detection or use start_quick_schema_creation when schema creation is authorized. This tool does not create or modify templates.
start_quick_schema_creationActionUpload one local file to automatically create extraction schemas/templates; use when the user authorized schema creation, which may consume credits. Returns run_id for get_quick_schema_creation or wait_for_quick_schema_creation, not an extraction task_id or export_job_id. Completed runs return generated template IDs and saved document IDs; inspect those before submitting another extraction. Supply upload_batch_id and source_upload_id only when provided by an external batched-upload workflow; MCP does not create upload batches. Starting again can create duplicate work.
get_quick_schema_creationRead-onlyCheck an existing quick-schema run_id once without waiting. Returns result.status and available progress, template IDs, saved document IDs, or failure details. If processing, call again later or use wait_for_quick_schema_creation. For completed results, use template_id for future extraction and saved_document_id or saved_documents[].document_id to fetch/download existing results. Do not start another schema-creation run just to check status.
wait_for_quick_schema_creationRead-onlyWait for an existing quick-schema run_id until result.status is completed, completed_with_errors, or failed. Terminal failure is returned in result, so inspect status and failed_documents rather than assuming a successful tool call means full success. Returns generated template IDs and saved document IDs for future extraction or result retrieval. SDK defaults are 5 seconds between polls and 300 attempts; choose a smaller max_poll_attempts for short client timeouts. On polling timeout, check or wait on the same run_id rather than starting another run.
get_task_resultsRead-onlyInspect one page of documents already available for an extraction task_id, including while processing. Each documents[].id is a document ID usable by fetch_document_result, fetch_json_results, or download_results; extraction_data contains that document's current data. Pass next_cursor as cursor with the same task_id to get the next page. next_cursor null ends this snapshot, not task processing; use wait_for_task_extraction to determine completion. To refresh later, omit cursor and deduplicate by document ID. This returns a page, not a complete export.
fetch_json_resultsActionExport one or more existing Suparse document IDs as JSON into the MCP response, grouped by task in results (task_id, original_file, total_documents_extracted, documents). Use fetch_document_result for a direct single-document read without submitting an export; use download_results for large results, local files, CSV, XLSX, or Google Sheets. This tool only exports JSON and does not unpack ZIP artifacts. On export timeout, retain export_job_id for the export-job tools or replay the identical export with its retained idempotency_key. Does not delete documents; cleanup is explicit through delete_documents.
fetch_document_resultRead-onlyRead structured JSON for one processed Suparse document_id directly, without submitting an export job or saving a local file. Returns task_id, original_file, total_documents_extracted, and documents containing extracted_data. Get document IDs from extraction results or get_task_results (documents[].id); do not substitute a task_id. Use fetch_json_results for a multi-document JSON export or download_results to save an export. Does not wait for extraction to finish.
Show all 17 toolsShow fewer tools
download_resultsActionExport existing Suparse document IDs as JSON, CSV, XLSX, or Google Sheets to local disk. Returns output_path plus requested_format, artifact_format and content_type. Existing output files are overwritten: choose a new path unless replacement is intended. CSV/XLSX may return ZIP; its extension is corrected to .zip. Set unpack:true to also extract the separate files into a fresh folder and return output_paths. JSON is saved as parsed task groups. Google Sheets requires an immediate API response and saves metadata as JSON. For a known export_job_id use download_export_job to recover the original artifact. Does not delete remote documents.
get_export_jobRead-onlyCheck one existing export_job_id from an export response or error recovery; this is not an extraction task_id or document_id. Returns job status, generated/excluded counts, error details, expiry, and artifact metadata without waiting or downloading. Use wait_for_export_job if still running, then download_export_job for a completed artifact. Inspect exclusions and errors before claiming all requested documents were exported. Status and format strings may include values unknown to this client.
wait_for_export_jobRead-onlyWait for an existing export_job_id; does not submit an export or download its file. On completion, use download_export_job to save the artifact. Defaults to a 60000-millisecond completion wait including polling retries, not the full MCP call. On polling timeout, keep the export_job_id and call get_export_job or wait_for_export_job again instead of submitting another export. Failed, expired, or unsupported jobs may produce errors; inspect recovery details.
download_export_jobActionSave the artifact of an existing completed export_job_id to local disk, including after reconnecting. Preserves original bytes, including ZIP; does not parse JSON, unpack ZIP, wait for completion, or submit another export. Use get_export_job or wait_for_export_job first if needed. Verifies artifact size and SHA-256 before atomic publication. Returns output_path. overwrite defaults false; enable only when replacing a local file is intended. An expired artifact cannot be recovered by retrying this download.
delete_documentsActionDelete documents from Suparse remotely using document IDs, not task IDs, export job IDs, or local paths. Use only when deletion or cleanup is requested, after confirming any required results are safely saved. Deleted IDs cannot be used for later result retrieval or exports. Does not delete local input or exported files. Repeating deletion does not create new work, though its returned boolean may change.
Configuration
SUPARSE_API_KEYRequiredSecretSuparse API key used to authenticate requests.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesuparse/suparse-mcp is public and reachablegithub.com/suparse/suparse-mcp ↗Pass
- Package names this repository as its source@suparse/mcp names suparse/suparse-mcp as sourcenpmjs.com/package/@suparse/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-19github.com/suparse/suparse-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @suparse/mcpPass
- No critical advisory in the package or its dependencies102 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSuparse 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:
SUPARSE_API_KEY~/.config/suparse/config.json
Prefer passing SUPARSE_API_KEY through your client's environment or secret-input support. The fallback file is implemented by Suparse and contains { "apiKey": "your_api_key" }. Protect it as a credential file.
Replace your_api_key in the examples below. Client env settings and CLI --env options can save the key in client configuration; keep files containing real keys out of Git and shared workspaces. CLI commands containing a key may also appear in shell history. Use scoped API keys where available.
Local Installation
Install your chosen client first and ensure Node.js 20+ and npx are available to it. These setups launch @suparse/mcp as a local stdio process:
- Claude Code
- Claude Desktop
- Codex CLI / IDE
- Cursor
- VS Code / GitHub Copilot
- Gemini CLI
- Windsurf / Cascade
Merge JSON examples into existing configuration rather than replacing other servers. After connecting, use the template-listing check to verify Suparse authentication.
Claude Code
Install for all your projects with user scope:
claude mcp add --scope user --transport stdio suparse \
--env SUPARSE_API_KEY=your_api_key \
-- npx -y @suparse/mcp
Keep the server name (suparse) before --env; Claude Code can otherwise parse it as another environment variable and report Invalid environment variable format.
To change an existing registration (for example, its API key or launch command), remove it before running the add command again:
claude mcp remove --scope user suparse
Use the name and scope from your original installation. For a user-scoped local test registered as suparse-local, run claude mcp remove --scope user suparse-local. After adding the updated registration, fully exit Claude Code and start a fresh session to load the new configuration.
Check the configuration and connection:
claude mcp list
claude mcp get suparse
Inside Claude Code, use /mcp to inspect status and tools, then run the template-listing check. See the Claude Code MCP documentation.
Claude Desktop
Open your config file at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS 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"
}
}
}
}
Fully quit and reopen Claude Desktop, confirm Suparse appears among the available tools, then run the template-listing check.
If Windows reports a process-start error for npx, replace the server's command and args with:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@suparse/mcp"]
}
Keep the existing env block. This workaround is only needed for clients that cannot launch npx.cmd directly.
Codex
The preferred installation is through the CLI:
codex mcp add suparse \
--env SUPARSE_API_KEY=your_api_key \
-- npx -y @suparse/mcp
After installation, add tool_timeout_sec = 300 inside the existing [mcp_servers.suparse] table in ~/.codex/config.toml. The CLI command does not set this timeout.
Alternatively, configure the server manually in ~/.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. The CLI and IDE extension share this configuration. See the Codex MCP documentation.
Verify the configured server:
codex mcp list
In an interactive Codex session, use /mcp to inspect active servers, then run the template-listing check.
Cursor
Add this to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for the current project:
{
"mcpServers": {
"suparse": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@suparse/mcp"],
"env": {
"SUPARSE_API_KEY": "${env:SUPARSE_API_KEY}"
}
}
}
}
Set SUPARSE_API_KEY in Cursor's environment before launching it; the ${env:SUPARSE_API_KEY} reference keeps the key out of the JSON file. Restart Cursor after changing its environment. Alternatively, put the key in an untracked personal configuration.
Open Cursor's MCP settings, confirm Suparse is enabled and its tools are available, then run the template-listing check in Agent chat. See the Cursor MCP documentation.
VS Code / GitHub Copilot
For Copilot CLI, install and verify with:
copilot mcp add suparse \
--env SUPARSE_API_KEY=your_api_key \
--timeout 300000 \
-- npx -y @suparse/mcp
copilot mcp list
The timeout is in milliseconds and allows up to five minutes for tool discovery and calls. Then run the template-listing check in Copilot CLI. See the Copilot CLI command reference.
For a portable Copilot setup, create .mcp.json in the workspace root. For a personal installation, use ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json if configured):
{
"mcpServers": {
"suparse": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@suparse/mcp"],
"env": {
"SUPARSE_API_KEY": "your_api_key"
},
"tools": ["*"]
}
}
}
Keep any file with a real key untracked. For a workspace configuration using VS Code's password input, use .vscode/mcp.json instead:
{
"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}"
}
}
}
}
The VS Code format uses servers; the portable format uses mcpServers. Choose one setup to avoid duplicate servers. Interactive inputs are not forwarded to Copilot harness sessions; use the portable setup for those sessions.
Run MCP: List Servers from the Command Palette, select Suparse and start it, then run the template-listing check in agent chat. See the VS Code MCP configuration reference.
Gemini CLI
Install for your user account:
gemini mcp add --scope user \
--env SUPARSE_API_KEY=your_api_key \
suparse npx -y @suparse/mcp
This writes the server configuration to ~/.gemini/settings.json. Check connection status with:
gemini mcp list
In an interactive session, use /mcp list to inspect tools, then run the template-listing check. See the Gemini CLI MCP documentation.
Windsurf / Cascade
These instructions target the legacy Cascade agent. For the newer default Devin Local agent, follow the Devin CLI MCP configuration documentation; its configuration locations and migration behavior depend on the installed version, even where paths overlap with Cascade.
Open the MCP configuration from Cascade's MCP controls. Windsurf installations use ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows). Cascade in current Devin Desktop releases uses ~/.config/devin/mcp_config.json (or $XDG_CONFIG_HOME/devin/mcp_config.json) on macOS/Linux and %APPDATA%\devin\mcp_config.json on Windows. Opening the file from Cascade selects the path for your installed version.
Add Suparse under mcpServers:
{
"mcpServers": {
"suparse": {
"command": "npx",
"args": ["-y", "@suparse/mcp"],
"env": {
"SUPARSE_API_KEY": "your_api_key"
}
}
}
}
Save the file, refresh the MCP list or restart the client, and confirm Suparse and its tools are enabled in Cascade. Run the template-listing check. See the Cascade MCP documentation.
Verify Your Installation
In your client's agent chat, ask:
Use Suparse's
list_templatestool to list my team's available extraction templates.
Approve the tool call if prompted. A successful response confirms both the MCP connection and Suparse API authentication; an empty team_templates list is valid if your team has no templates. This check does not upload or process a document.
If the server fails to start, check that Node.js 20+ and npx are on the client's PATH, and inspect its MCP logs. For authentication errors, check the key passed to the server or the Suparse fallback file. Desktop applications may not inherit environment variables set in a terminal.
Verify Document Processing (Optional)
Processing may consume Suparse credits. Use a small sample invoice or receipt containing data you are comfortable uploading to Suparse.
- Put the sample PDF somewhere accessible to the MCP server and use its absolute path (see local paths).
- Ask your client: "Use Suparse's
start_file_extractionto extract structured data from/absolute/path/to/sample.pdf. Return the task ID and any document IDs or processing status provided. Do not delete the uploaded document." - Call
wait_for_task_extractionwith the returned task ID. If processing is still running, retain the ID and poll again; do not upload the file again. - Once processing completes, use a returned document ID to call
fetch_document_result. If necessary, useget_task_resultswith the task ID to discover document IDs.
This checks local file access, authentication, upload, processing, and result retrieval. Keep the uploaded document unless you explicitly want to delete it later.
Tools
| Goal | Recommended tool |
|---|---|
| Process a document, then obtain task/document IDs | extract_file with the default result_mode: "defer" |
| Start processing and return after upload confirmation | start_file_extraction |
| Get JSON directly in the MCP response | extract_file with result_mode: "return_json" |
| Start processing many documents | start_folder_extraction |
| Inspect intermediate results | get_task_results |
| Save a CSV/XLSX/JSON file | download_results |
| Download a completed export after reconnecting | download_export_job |
defer uploads and polls until processing reaches a terminal state or polling fails; it defers the result export, not the processing wait. The start-only tools return task IDs after upload confirmation without polling for processing completion. Use them when you need an ID promptly, especially for long jobs or human review.
return_json returns full results in both text and structured content. Large documents or batches can consume substantial assistant context; prefer download_results to save exports for those jobs.
Local Paths
Input and output paths must be accessible to the machine and operating-system process running Suparse MCP. Relative paths such as ./invoice.pdf resolve against the server process's current working directory, which the MCP client chooses at launch; this may differ from your open project or chat's directory. File paths pass directly to the Node SDK's filesystem operations, and folder paths are normalized with path.resolve against that same working directory. Relative export paths also use the process's working directory; omitted output paths default there. The server does not expand ~ in tool path arguments.
Prefer absolute paths when the working directory is uncertain. Use paths for the server's operating system: for example, C:\Users\you\invoice.pdf for a Windows process or /mnt/c/Users/you/invoice.pdf for a WSL2 process with that drive mounted. A path on another machine or outside the server's accessible filesystem cannot be read just because it appears in chat.
Credits, Deletion, and Retries
Document processing and automatic schema creation may consume Suparse credits. Uploading the same file again can create another processing submission. If a request times out, recover using the retained task ID, export job ID, or idempotency key before submitting new work.
delete_documents deletes documents from Suparse remotely; it does not just remove local temporary files. The cleanup option on combined extraction tools can also delete remote documents after a verified export. Request deletion only after confirming that the results you need are safely saved.
The server already supplies MCP annotations: status, template, and result inspection tools are read-only; upload/schema-creation tools are mutating and non-idempotent; combined extraction is marked potentially destructive because it can clean up; and delete_documents is marked destructive. Export submission tools are not advertised as universally idempotent: safe replay requires the same key and identical request options. Disk export tools can also write or overwrite local files. These hints help clients assess tool calls, but do not enforce permissions or make arbitrary retries safe.
Tool Reference
extract_file,extract_folder: Combined upload and processing.deferis the default and returns task/document IDs after polling; a task can bepartially_completed.return_jsonreturns exported groups with per-input task status and document IDs; partial tasks and empty exports are reported as incomplete.cleanupis best-effort and valid only withreturn_json.start_file_extraction,start_folder_extraction: Upload and return task IDs immediately, without polling or exporting. Folder scans are sorted, nonrecursive, and limited to 10 concurrent uploads.wait_for_task_extraction: Poll a remote task. Defaults to 2 seconds between polls and 3 attempts; retries and SDK backoff mean this is not a strict wall-clock deadline.get_task_results: Read one bounded page of partial task documents. The opaque cursor ends a snapshot, not task processing; a fresh call may show more documents.list_templates: List summary or full template records, grouped into directly usableteam_templatesand discovery-onlysystem_templates.start_quick_schema_creation,get_quick_schema_creation,wait_for_quick_schema_creation: Start and inspect automatic schema creation. The run ID is separate from task, document, and export job IDs.fetch_json_results: Return validatedTaskExport[]JSON by document ID. It does not unpack ZIP artifacts or accept arbitrary JSON schemas.fetch_document_result: Fetch one document's structured JSON result through the direct single-document endpoint.download_results: Export documents and save the response to a local path. Supports JSON, CSV, XLSX, and immediate Google Sheets. Existing output paths follow the SDK overwrite behavior.get_export_job,wait_for_export_job,download_export_job: Inspect, wait for, and download a known remote export job across MCP restarts. Downloads preserve original bytes, including ZIP, and verify the artifact before atomic publication.download_export_jobdefaults tooverwrite: false.delete_documents: Delete remote documents by ID. Use after confirming a successful export/download when cleanup is requested.
Export Formats
fetch_json_results accepts:
| Input | Values | Default |
|---|---|---|
export_type |
original, unified |
unified |
JSON exports are returned as structured results. fetch_json_results and download_results accept wait_timeout_ms (positive integer milliseconds, default 60000) and an optional UUID idempotency_key. The wait value bounds completion waiting, including polling retries; submission and transfer are separate phases, so MCP clients still need enough total tool time. If a response is lost, replay the same document IDs, format, export type, layout, and key.
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. Immediate Google Sheets responses work; background Google Sheets is unsupported. The disk tool saves the Sheets response metadata, including URLs, rather than a spreadsheet binary. 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. A known-job download preserves raw artifact bytes and is the path for ZIP or exact JSON artifacts.
CSV/XLSX exports can return a ZIP containing several files (for example, invoices
and bank statements). Both download tools report requested_format,
artifact_format, and content_type, and correct the saved extension to match
the artifact. An explicit results.xlsx path therefore becomes results.zip
when the API returns an archive; check the returned output_path.
For separate local files, call download_results with unpack: true:
{"document_ids":["invoice-id","statement-id"],"format":"xlsx","output_path":"/absolute/path/results.xlsx","unpack":true}
The ZIP is retained, and output_paths lists the extracted files in a fresh
results_files-* folder next to it. Existing extracted files are never replaced.
A single workbook stays .xlsx and appears directly in output_paths.
Unpacking defaults to false, applies only to CSV/XLSX, and rejects unsafe archive
paths, links, duplicate destinations, more than 1000 entries, or more than 512 MiB
of uncompressed data. Failed extraction removes partial files; error recovery
includes saved_artifact_path if the archive was already saved.
download_export_job always preserves the original artifact without unpacking.
CSV/XLSX download_results buffers the artifact through the SDK's raw-download
API; known-job recovery streams and verifies the artifact before publication.
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.
Explicit return_json requests return complete JSON in both text and structured content, including when cleanup is enabled. Its tasks records preserve each polled input’s task ID, status, and document IDs. Partial completion and empty exports increase failed_count while preserving any exported data; their parent tasks are retained during cleanup. Combined extraction accepts wait_timeout_ms for each JSON export, defaulting to 60000 milliseconds; it is ignored in defer mode. Its optional exports records associate generated idempotency keys and accepted job IDs with each local input. Combined extraction does not accept caller-supplied idempotency keys.
Cancelled folder responses account for all scanned files. Inputs that never started appear in failed with cancelled: true, unstarted: true, and code OPERATION_NOT_STARTED; failed_count includes them. These entries remain in source order and distinguish inputs safe to start from submitted tasks needing recovery. A known export job takes recovery priority, followed by replaying an identical export with its retained key, then task polling.
Important: cleanup on extract_file and extract_folder is only valid with result_mode: "return_json". Cleanup is best-effort and requires a fully completed task and a JSON export covering every requested document ID. Missing or unverifiable coverage produces an INCOMPLETE_EXPORT failure and retains the parent. It retains partial tasks, empty exports, and inputs whose backend work is uncertain. Folder cleanup waits for all extraction workers to settle and is skipped after cancellation. For CSV/XLSX/Google Sheets or saved JSON files, use start or combined extraction, wait for the task, download the result, then call delete_documents if requested. A local artifact write failure alone does not prove backend work is still running. When cleanup is requested, cleanup reports its status and deleted or retained document IDs in both text and structured results. Retained IDs include deletions that could not be confirmed. Combined extraction progress counts settled input files and increases with every notification.
extract_file, extract_folder, start_file_extraction, and start_folder_extraction accept template_id, split, pdf_password, folder_id, and auto_approve. Approval defaults to true. Set auto_approve: false only when human review is requested, and use the start-only tools so the task ID is returned before processing waits. MCP cannot perform human review or approve documents; retain the task ID and resume polling after review is complete. This does not create or report a backend awaiting_approval status. Treat pdf_password as sensitive input. MCP redacts it from returned errors, metadata, partial results, and progress, while an MCP client may retain submitted tool arguments according to its own behavior.
Google Sheets Requirements and Results
- Connect Google Sheets in Suparse before requesting
format: "google_sheets"; the SDK requires a working Google integration. - The Suparse integration supports creating a spreadsheet or appending to an existing one. This MCP tool exposes no target spreadsheet ID or append option, and the SDK does not specify which destination behavior its export endpoint chooses. Selecting a destination or explicitly appending rows is not supported through this MCP server.
- Only immediate Google Sheets export responses are supported here; background Google Sheets jobs cannot be downloaded through this workflow.
download_resultssaves a JSON metadata file and returnsoutput_pathplus availablegoogle_sheets_metadata, which may include spreadsheet or folder URLs. It does not save a local.xlsxfile. Useformat: "xlsx"for that.
Suparse MCP questions
How do I add Suparse MCP to Claude Code?
Run claude mcp add --env 'SUPARSE_API_KEY=<YOUR_SUPARSE_API_KEY>' suparse-mcp -- npx -y @suparse/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Suparse MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Suparse MCP provide?
It exposes 17 tools, including extract_file, extract_folder, start_file_extraction, start_folder_extraction, wait_for_task_extraction.
What formats can I export extracted data into?
You can export extracted data into JSON, CSV, XLSX, or Google Sheets.
How do I authenticate with the Suparse MCP server?
You can authenticate using a SUPARSE_API_KEY environment variable or by placing your key in a configuration file at ~/.config/suparse/config.json.
Can the server process encrypted PDFs?
Yes, the server can process single files or folders, including encrypted PDFs.