tikz-mcp

tikz-mcp

A lightweight MCP (Model Context Protocol) server that compiles TikZ code into high-resolution PNG images. Lets AI assistants render and preview LaTeX/TikZ diagrams during conversations.

Features

• Single tool: compile_tikz -- pass TikZ code, get a PNG image
• Auto-wrapping: Raw TikZ commands are automatically wrapped in a standalone document
• Custom preamble: Pass your own \usepackage / \usetikzlibrary commands
• High resolution: Output at 1000 DPI by default, with transparent background
• Graceful errors: LaTeX compilation errors are captured and returned as readable messages
• Style guide: Built-in aesthetic rules injected into AI instructions for consistent, publication-quality output
• Self-verification: AI is instructed to inspect its own output and fix issues before presenting to the user
• Zero idle cost: Uses stdio transport -- no background process when not in use

Prerequisites

• Python >= 3.10
• LaTeX: pdflatex in PATH (e.g. via MacTeX or TeX Live)
• Poppler: pdftoppm in PATH (install via brew install poppler), OR Ghostscript gs in PATH (ships with MacTeX)

Installation

pip install tikz-mcp

Or install from source:

git clone https://github.com/FlorianHuo/tikz-mcp.git
cd tikz-mcp
pip install .

Usage

As an MCP server (stdio)

Add to your MCP client config (e.g. Antigravity settings.json, Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "tikz-mcp": {
      "command": "tikz-mcp",
      "args": []
    }
  }
}

Or run with python:

{
  "mcpServers": {
    "tikz-mcp": {
      "command": "python3",
      "args": ["-m", "tikz_mcp.server"]
    }
  }
}

Tool: compile_tikz

Parameter	Type	Required	Description
tikz_code	string	Yes	TikZ code (raw commands or full document)
preamble	string	No	Custom LaTeX preamble (replaces default)

Example -- raw TikZ code:

\begin{tikzpicture}
  \draw[thick, ->] (0,0) -- (3,0) node[right] {$x$};
  \draw[thick, ->] (0,0) -- (0,3) node[above] {$y$};
  \draw[blue, thick] (0,0) circle (2);
\end{tikzpicture}

The server auto-wraps this in a standalone document with common TikZ libraries loaded.

Example -- full document:

\documentclass[border=5pt]{standalone}
\usepackage{tikz}
\begin{document}
\begin{tikzpicture}
  \fill[red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{document}

Output

Rendered PNGs are saved to $HOME/.tikz-mcp/output/ and the full path is returned.

Default Preamble

When raw TikZ code is provided (without \documentclass), the following preamble is used:

\usepackage{tikz}
\usepackage{amsmath,amssymb}
\usetikzlibrary{
    arrows.meta, calc, decorations.pathmorphing,
    decorations.markings, patterns, positioning,
    shapes.geometric, shapes.misc, fit, backgrounds,
    intersections, through, matrix, trees,
}

Override by passing a custom preamble parameter.

License

MIT

Changelog

v0.2.0

• Embedded STYLE_GUIDE.md into server instructions with inline code patterns and anti-patterns
• Added physical/mathematical accuracy rules (real hyperbolas, correct slopes)
• Added TikZ pitfalls section (dimension overflow, hatched fill workarounds)
• Added self-verification workflow: AI must inspect output and fix issues before presenting
• Default standalone border changed from 5pt to 8pt

v0.1.0

• Initial release
• compile_tikz tool with auto-wrapping, custom preamble, 1000 DPI output
• stdio transport for zero idle resource usage