Mathpix CLI
mpx is the open-source Mathpix command-line tool for OCR and document conversion. Use it with the hosted Mathpix API or your own Private Cloud OCR deployment.
Developers and coding agents can convert documents with a single command. The CLI handles uploads, status polling, and downloads.
Install and configure
On macOS, Linux, or Windows with WSL:
curl -fsSL https://mathpix.com/mpx-cli/install.sh | sh
mpx configure
Use the app_id and app_key from Mathpix Console. For the hosted API, keep the endpoint set to https://api.mathpix.com. This is the base URL; do not enter a route such as /v3/text or /v3/pdf.
The configuration prompt also lets you choose normal or quiet progress output. Press Enter to keep the default. See configuration for profiles, environment variables, and progress settings.
Native Windows downloads are available on the GitHub releases page.
Convert a file or folder
Commands use mpx <service> <command>. The scs service uses the hosted OCR and conversion API. For a single file, the destination extension selects the output format:
mpx scs convert paper.pdf paper.docx
mpx scs convert paper.md paper.docx
mpx scs convert equation.png equation.mmd
For a folder, --map selects conversions by input extension:
mpx scs convert ./scans/ ./out/ --map pdf:docx,md:docx
Outputs are written to the file or directory you specify. Common OCR options have flags; other options can be passed as JSON:
mpx scs convert paper.pdf paper.mmd --options-json '{"rm_fonts": true}'
Files API and batch jobs
Use mpx scs jobs for server-side batch jobs through the Files API. To inspect the available commands:
mpx scs jobs --help
For a single file, --async selects the Files API. Use --destination to specify your own output bucket. The CLI waits for completion and downloads the requested output.
See the SCS command reference for submission options and storage configuration.
Private Cloud OCR
Use the pco service and your deployment's base URL:
mpx pco --endpoint http://pco.internal:8080 convert ./scans/ ./out/ --formats docx
See the PCO CLI guide for configuration, batch processing, and status commands.