LaTeX Workspace MCP

Restricted Model Context Protocol tools for local LaTeX projects. The server lets an AI assistant inspect a configured workspace, make narrow .tex edits, compile with a fixed latexmk command, and verify that the generated PDF and image assets are usable.

Features

• Scan LaTeX projects and infer the main file, engine, bibliography mode, included files, figure references, citations, and labels.

• Read .tex files, create or overwrite .tex files only with explicit overwrite approval, and replace exactly one unique text occurrence.

• Compile a selected main file with pdflatex or xelatex through latexmk into the document-local build/ directory.

• Analyze build logs for errors, warnings, undefined references, and undefined citations.

• Check citation keys, duplicate labels, undefined labels, and figure path existence.

• Validate image assets before a build with validate_latex_assets, including reachable \input/\include files, first-page PDF metadata, dimensions for PNG/JPEG/PDF assets, and similar-path suggestions.

• Verify generated PDFs with verify_latex_pdf, including MIME type, page count, page sizes, and embedded image metadata from pdfimages.

• Run the full asset-check, build, and PDF-verification flow with build_and_verify_latex.

• Use either stdio MCP for local editors or Streamable HTTP MCP for ChatGPT-style clients.

Related MCP server: chatgpt-codex-tools-mcp

Security Model

• Every path is resolved under the configured --root directory. Paths outside the root are rejected.

• Write tools only accept project-relative .tex files. There is no delete, rename, arbitrary shell, or generic file-write API.

• write_tex_file refuses to overwrite existing files unless overwrite: true is supplied.

• replace_tex_text requires one exact unique match. Empty, missing, or multiple matches are rejected.

• Compilation uses a fixed latexmk command with shell: false, disabled shell escape, bounded output, and build artifacts under build/.

• The HTTP server requires an API key from LATEX_MCP_API_KEY_FILE and accepts either Authorization: Bearer ... or X-API-Key.

• The HTTP server binds to 127.0.0.1 by default and allows only localhost,127.0.0.1 host headers unless LATEX_MCP_ALLOWED_HOSTS is set.

Requirements

• Node.js 20 or newer.

• TeX Live or another LaTeX distribution with latexmk, pdflatex, and optionally xelatex.

• PDF utilities: file, pdfinfo, and pdfimages.

On Debian or Ubuntu, the PDF utilities are usually provided by file and poppler-utils.

Install

git clone https://github.com/YOUR_GITHUB_USER/latex-workspace-mcp.git
cd latex-workspace-mcp
npm install

Use an absolute project root when starting either server:

node server.mjs --root /path/to/latex/project

Stdio MCP

Use stdio when the MCP client launches local commands directly.

{
  "mcpServers": {
    "latex-workspace": {
      "command": "node",
      "args": ["/path/to/latex-workspace-mcp/server.mjs", "--root", "/path/to/latex/project"]
    }
  }
}

HTTP MCP

Create an API key file with permissions limited to the service user:

install -d -m 700 ~/.config/latex-workspace-mcp
openssl rand -base64 48 > ~/.config/latex-workspace-mcp/api-key
chmod 600 ~/.config/latex-workspace-mcp/api-key

Start the loopback HTTP server:

LATEX_MCP_API_KEY_FILE="$HOME/.config/latex-workspace-mcp/api-key" \
LATEX_MCP_HTTP_HOST=127.0.0.1 \
LATEX_MCP_HTTP_PORT=8787 \
LATEX_MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
node http-server.mjs --root /path/to/latex/project

The MCP endpoint is http://127.0.0.1:8787/mcp. Unauthenticated calls should return 401.

If you put a trusted reverse proxy in front of the server, keep the origin private and set LATEX_MCP_ALLOWED_HOSTS to the exact host headers your proxy sends.

systemd

Copy examples/latex-mcp-http.service.example and replace YOUR_PROJECT_ROOT with the absolute LaTeX workspace root. Keep LATEX_MCP_HTTP_HOST=127.0.0.1 when the proxy runs on the same machine.

ChatGPT Prompt Pattern

Use a prompt that keeps edits precise and makes the verification flow explicit:

Use the LaTeX Workspace MCP for this project. Before changing figure paths, call validate_latex_assets with the project-relative main_file. For source edits, prefer replace_tex_text and only use write_tex_file with overwrite: true when I explicitly ask for a full-file replacement. After any document or image-path change, call build_and_verify_latex. If the build fails, use analyze_log and validate_latex_assets to make the smallest precise repair.

For projects with multiple main.tex files, always pass a project-relative main_file, such as paper/main.tex.

Image And First-Page Validation Workflow

1. Put images under the configured project root and reference them with paths relative to the main file directory.

2. Call validate_latex_assets before compiling. Missing \includegraphics assets stop build_and_verify_latex before LaTeX runs.

3. For PNG and JPEG assets, the tool reports dimensions from the file header.

4. For PDF assets, the tool calls pdfinfo and reports first-page page-size metadata without extracting binary content.

5. After compilation, call verify_latex_pdf or build_and_verify_latex to confirm the expected build/<stem>.pdf exists, has pages, and lists embedded images.

Tool Summary

• get_project_info

• scan_project

• analyze_log

• check_citations

• check_labels

• check_figures

• validate_latex_assets

• verify_latex_pdf

• build_and_verify_latex

• list_tex_files

• read_tex_file

• write_tex_file

• replace_tex_text

• compile_latex

License

MIT