内容
# mathpix-mcp
一款 **Model Context Protocol 服务器**，用于 [Mathpix](https://mathpix.com) 的光学字符识别（OCR），支持 **stdio** 或 **Streamable HTTP**（带有 bearer-token 认证）。它将 Mathpix 的转换功能以 MCP 工具的形式暴露给大型语言模型（LLM）或代理，使其能够将图像和 PDF/DOCX/PPTX 文档转换为 LaTeX 和 Markdown。
## 工具列表
| 工具 | 用途 |
|------|---------|
| `convert_document_tool` | 将 PDF/DOCX/PPTX 转换为 Markdown/LaTeX/HTML（URL 或本地路径）。支持 `output_path` 并自动将大输出保存到文件中，以防止模型上下文溢出。 |
| `convert_image_tool` | 将图像转换为 LaTeX/文本/MathML 等。 |
| `convert_strokes_tool` | 将手写笔画转换为 LaTeX/文本。 |
| `batch_convert_tool` | 多张图像，可选并发（`parallel`、`max_parallel`）。 |
| `check_document_status_tool` | 轮询异步文档转换。 |
| `search_results_tool` | 搜索最近的捕获（大小受限）。 |
| `get_usage_tool` / `get_account_info_tool` | 账户/使用情况信息。 |
| `list_formats_tool` | 列出支持的输出格式。 |
## 要求
- Ruby >= 3.2
- Mathpix API 凭证（`MATHPIX_APP_ID`、`MATHPIX_APP_KEY`）
## 安装
从 RubyGems（提供 `mathpix-mcp` / `mathpix-mcp-http` 可执行文件）：
```bash
gem install mathpix-mcp
```
或直接从 GitHub（在 Gemfile 中）：
```ruby
gem 'mathpix-mcp', git: 'https://github.com/georgedouzas/mathpix-mcp'
```
或从克隆的仓库本地构建：
```bash
gem build mathpix-mcp.gemspec
gem install ./mathpix-mcp-*.gem
```
或使用 Bundler 从克隆的仓库运行：
```bash
bundle install
cp .env.example .env # 添加你的 MATHPIX_APP_ID / MATHPIX_APP_KEY
```
## 运行（stdio）
```bash
mathpix-mcp # 如果作为 gem 安装
# 或
bundle exec mathpix-mcp
```
它通过 stdio 进行 MCP 通信。凭证从 `.env`（当从项目目录启动时）或进程环境中读取。
## 运行（HTTP / Streamable HTTP）
HTTP 传输需要 bearer token（`MATHPIX_MCP_TOKEN`）——每个请求都必须发送 `Authorization: Bearer <token>`。它默认绑定到 `127.0.0.1:3000`（`MATHPIX_MCP_HOST` / `MATHPIX_MCP_PORT`）。
```bash
export MATHPIX_MCP_TOKEN=$(openssl rand -hex 32)
mathpix-mcp-http # 如果作为 gem 安装
# 或
bundle exec mathpix-mcp-http
# 或，使用任意 Rack 服务器：
bundle exec puma config.ru -b tcp://127.0.0.1:3000
```
示例请求：
```bash
curl -s http://127.0.0.1:3000/ \
-H "Authorization: Bearer $MATHPIX_MCP_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
不要在没有 TLS-terminating 反向代理的情况下将其公开暴露在公共接口上。
## 连接代理
stdio 和 HTTP 的每个客户端设置都在 **[docs/CLIENTS.md](docs/CLIENTS.md)** 中——涵盖 Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、VS Code（Copilot）、Windsurf、Zed、Continue、Cline、Goose、代理 SDK 和用于其他任何情况的通用 `mcp-remote` 桥接。
最快捷的方式——stdio 上的 Claude Code：
```bash
claude mcp add mathpix -e MATHPIX_APP_ID=... -e MATHPIX_APP_KEY=... -- mathpix-mcp
```
## 部署（HTTP）
生产部署——TLS 反向代理（Caddy/nginx）、systemd、Docker / docker-compose 和安全检查列表——在 **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** 中。包含一个 `Dockerfile`：
```bash
docker build -t mathpix-mcp .
docker run --rm -p 3000:3000 \
-e MATHPIX_APP_ID=... -e MATHPIX_APP_KEY=... \
-e MATHPIX_MCP_TOKEN=$(openssl rand -hex 32) mathpix-mcp
```
## 注意
- 如果 Mathpix 的后端拒绝格式错误的 PDF（例如 `pdftoppm` 崩溃），该工具会返回描述性错误；通常修复 PDF（`gs -o fixed.pdf -sDEVICE=pdfwrite in.pdf`）可以解决这个问题。
## 许可证
MIT — 见 [LICENSE](LICENSE)。
