@suparse/mcp

@suparse/mcp

MCP stdio server for the Suparse Document Processing API.

Use this package to connect Suparse document extraction to local MCP clients such as Claude Code and Codex.

Requirements

• Node.js 20+
• A Suparse API key

Authentication

The MCP server reads credentials from:

• SUPARSE_API_KEY
• ~/.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"]

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

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 metadata for templates available to the authenticated account.
• 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.

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. 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.

Development

Build the package:

pnpm --filter @suparse/mcp build

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node packages/mcp/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.