mathpix-mcp

A Model Context Protocol server for Mathpix OCR, over stdio or Streamable HTTP (bearer-token auth). It exposes Mathpix conversion as MCP tools so an LLM/agent can turn images and PDF/DOCX/PPTX documents into LaTeX and Markdown.

Tools

Tool	Purpose
convert_document_tool	PDF/DOCX/PPTX → Markdown/LaTeX/HTML (URL or local path). Saves output to a file and returns a path + preview so it doesn't overflow the model context.
convert_image_tool	Image → LaTeX/text/MathML/etc. Result is written to a file (path + preview returned).
convert_strokes_tool	Handwritten strokes → LaTeX/text.
batch_convert_tool	Multiple images, optionally concurrent (parallel, max_parallel).
check_document_status_tool	Poll an async document conversion.
search_results_tool	Search recent captures; full content (when requested) is written to files.
get_usage_tool / get_account_info_tool	Usage statistics and account identifiers.
list_formats_tool	List supported output formats.

OCR results (LaTeX/text/MathML/etc.) are always written to files rather than returned inline; tools return a file path, a short preview, and metadata. The destination follows the tool's output_path/output_dir argument, else MATHPIX_OUTPUT_DIR, else the system temp dir.

Requirements

• Ruby >= 3.2 (CI runs 3.3 and 3.4)
• Mathpix API credentials (MATHPIX_APP_ID, MATHPIX_APP_KEY)

Install

From RubyGems (provides the mathpix-mcp / mathpix-mcp-http executables):

gem install mathpix-mcp

Or straight from GitHub (in a Gemfile):

gem 'mathpix-mcp', git: 'https://github.com/georgedouzas/mathpix-mcp'

Or build locally from a clone:

gem build mathpix-mcp.gemspec
gem install ./mathpix-mcp-*.gem

Or run from a clone with Bundler:

bundle install
cp .env.example .env                 # add your MATHPIX_APP_ID / MATHPIX_APP_KEY

Configuration

All configuration is via environment variables (loaded from .env when launched from the project directory, or from the process environment). Copy .env.example to .env as a starting point.

Variable	Required	Default	Description
MATHPIX_APP_ID	yes	—	Mathpix application id.
MATHPIX_APP_KEY	yes	—	Mathpix application key.
MATHPIX_OUTPUT_DIR	no	system temp dir	Where OCR results are written when a tool isn't given an explicit output_path/output_dir.
MATHPIX_MAX_FILE_SIZE_MB	no	10	Maximum local file size accepted for upload.
MATHPIX_HTTPS_ONLY	no	true	Upgrade/enforce HTTPS for remote sources.
MATHPIX_API_URL	no	https://api.mathpix.com/v3	Mathpix API base URL.
MATHPIX_TIMEOUT	no	30	Per-request timeout in seconds (1–300).
MATHPIX_LOG_LEVEL	no	(off)	Log verbosity to stderr: DEBUG/INFO/WARN/ERROR.
MATHPIX_MCP_TOKEN	HTTP only	—	Bearer token required by the HTTP transport.
MATHPIX_MCP_HOST	no	127.0.0.1	HTTP bind host.
MATHPIX_MCP_PORT	no	3000	HTTP bind port.

Run (stdio)

mathpix-mcp            # if installed as a gem
# or
bundle exec mathpix-mcp

It speaks MCP over stdio. Credentials are read from .env (when launched from the project directory) or the process environment.

Run (HTTP / Streamable HTTP)

The HTTP transport requires a bearer token (MATHPIX_MCP_TOKEN) — every request must send Authorization: Bearer <token>. It binds to 127.0.0.1:3000 by default (MATHPIX_MCP_HOST / MATHPIX_MCP_PORT).

export MATHPIX_MCP_TOKEN=$(openssl rand -hex 32)
mathpix-mcp-http                 # if installed as a gem
# or
bundle exec mathpix-mcp-http
# or, with a Rack server of your choice:
bundle exec puma config.ru -b tcp://127.0.0.1:3000

Example request:

curl -s http://127.0.

... [View full README on GitHub](https://github.com/georgedouzas/mathpix-mcp#readme)