Content
# TikZ HTTP MCP Server
## Declaration
Project comes from an existing open source project: [tikz-mcp-server](https://github.com/ChaNg1o1/tikz-mcp-server)
- This project adds an HTTP-Streamable interface on its basis to realize remote deployment.
- Added a one-click deployment script to achieve custom one-click deployment.
This is an HTTP server based on Model Context Protocol (MCP) specifically designed to render TikZ/LaTeX code into high-quality PNG images. It provides a `render_tikz` tool that allows clients to submit TikZ code via HTTP requests and receive rendered images.
Compatible with `Cherry Studio` client
## Feature List
* **TikZ Rendering**: Compiles TikZ/LaTeX code into PNG images and supports directly returning base64 encoded image data or accessible image URLs.
* **MCP Compatible**: Runs as an MCP server, providing `render_tikz_base64`, `render_tikz_url` and `install_tex_package` three tools.
* **Automatic Image Cleanup**: Generated images are automatically cleaned up periodically, defaulting to 1 day.
* **Minimal Image**: Provides a minimal Docker image containing only the necessary TeX packages, greatly reducing the image size.
* **Docker Deployment**: Provides a `deploy.sh` script to simplify deployment in a Docker environment.
* **Error Handling**: Captures errors during LaTeX compilation and image conversion and provides detailed error information.
## Getting Started
### Prerequisites
Before starting the server, make sure your system has the following software installed:
* **Docker**: For containerized deployment.
* **Docker Compose**: For managing multi-container Docker applications.
### Environment Variable Configuration
The project uses a `.env` file to configure environment variables. You can copy the `.env.example` file and rename it to `.env`, then modify the values in it as needed.
```bash
cp .env.example .env
```
The `.env` file contains the following example variables:
* `SERVICE_NAME`: The name of the Docker Compose service, defaults to `tikz-mcp-server`.
* `CONTAINER_NAME`: The explicit name of the Docker container, defaults to `tikz-mcp-server-container`.
* `PORT`: The external port the service listens on, defaults to `3000`.
* `PUBLIC_IP`: The public IP address, used to generate image URLs, defaults to `localhost`.
* `PUBLIC_PORT`: The public port, used to generate image URLs, defaults to `3000`.
* `DOMAIN`: (Optional) Domain name, if set, HTTPS domain name will be used preferentially to generate image URLs, such as `https://tikz.yourdomain.com`
### Deployment Steps
#### Full Image Deployment (includes all TeX packages, larger size)
1. **Clone the repository** (if not already cloned):
```bash
git clone git@github.com:JoeChen2me/tikz-http-mcp-server.git
cd tikz-http-mcp-server
```
2. **Run the deployment script**:
First, make sure the `deploy.sh` script has execute permissions:
```bash
chmod +x deploy.sh
```
Then, execute the `deploy.sh` script to build the Docker image and start the service:
```bash
./deploy.sh
```
#### Minimal Image Deployment (only includes necessary TeX packages, smaller size)
1. **Run the minimal deployment script**:
First, make sure the `deploy-minimal.sh` script has execute permissions:
```bash
chmod +x deploy-minimal.sh
```
Then, execute the script to build the minimal Docker image:
```bash
./deploy-minimal.sh
```
### Image Size Comparison
- **Full Image**: ~2-3GB (includes full TeX Live)
- **Minimal Image**: ~500-800MB (only includes necessary packages)
## Local Test Run
### Prerequisites
To run the Python script locally, you need to install the following dependencies:
#### System Dependencies (macOS/Linux)
```bash
# macOS
brew install imagemagick mactex
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y texlive-xetex texlive-latex-recommended texlive-pictures imagemagick fonts-noto-cjk
# CentOS/RHEL
sudo yum install -y texlive-xetex texlive-latex-recommended texlive-pictures ImageMagick fonts-noto-cjk
```
#### Python Dependencies
```bash
pip install mcp starlette uvicorn click anyio
```
### Local Startup Test
1. **Create image directory**
```bash
mkdir -p images
```
2. **Start the server**
```bash
python3 tikz_http_server.py --port 3000 --log-level INFO
```
3. **Test tool list**
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"method":"tools/list","params":{}}'
```
4. **Test TikZ rendering**
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method":"tools/call",
"params":{
"name":"render_tikz_base64",
"arguments":{"tikz_code":"\\begin{tikzpicture}\\draw (0,0) circle (1cm);\\end{tikzpicture}"}
}
}'
```
5. **Test installing TeX package** (only when needed)
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method":"tools/call",
"params":{
"name":"install_tex_package",
"arguments":{"package_name":"pgfplots"}
}
}'
```
### Environment Variables
The following environment variables can be used when running locally:
- `PUBLIC_IP`: Public IP address (default: localhost)
- `PUBLIC_PORT`: Public port (default: 3000)
- `LOG_LEVEL`: Log level (default: INFO)
Example:
```bash
PUBLIC_IP=localhost PUBLIC_PORT=3000 python3 tikz_http_server.py
```
The script will perform the following operations:
* Check if Docker and Docker Compose are installed.
* If Docker Compose is not installed, it will attempt to install it automatically.
* Load environment variables from the `.env` file (if it exists).
* **Check if the container is already running, and if it exists, stop and delete it.**
* Build a Docker image named `tikz-mcp-server:latest` (`docker-compose.simple.yml` explicitly specifies that the `Dockerfile` under the project root directory is used for building). The image name is based on `SERVICE_NAME`.
* Start a Docker container named `tikz-mcp-server-container` (the container name is based on `CONTAINER_NAME`) and map the internal `3000` port of the container to the external `${PORT}` port.
* Wait for the service to start and perform a health check.
### Service Address
After the service is successfully started, you can access the MCP server through the following address:
* **MCP Service Endpoint**: `http://localhost:${PORT}/mcp/`
### MCP Tool Usage Instructions
The server provides the following three tools:
1. **render_tikz_base64**: Renders TikZ code into PNG and returns base64 encoding
2. **render_tikz_url**: Renders TikZ code into PNG and returns an accessible URL
3. **install_tex_package**: Installs additional TeX packages (especially useful for minimal images)
#### Install TeX Package Example
When using a minimal image, if a specific TeX package is missing, you can use the `install_tex_package` tool:
```json
{
"package_name": "pgfplots"
}
```
Supported package name examples:
- `pgfplots` - Used to draw function graphs
- `tikz-cd` - Used for commutative diagrams
- `tkz-euclide` - Used for Euclidean geometry
- `circuitikz` - Used for circuit diagrams
### MCP Client Configuration
The `mcp_server_configs.json` file in the project root directory contains server configuration examples for different MCP clients (such as Claude Desktop, VSCode, Windsurf, Cline, Cursor). You can refer to this file and configure it accordingly based on the type of client you are using.
For example, here is a general MCP client configuration example:
```json
{
"type": "http",
"url": "http://localhost:${PORT}/mcp/",
"transport": "streamable-http"
}
```
### Common Docker Commands
#### Full Image Commands
After the service is deployed, you can use the following `docker-compose` commands to manage the service:
* **View Logs**:
```bash
docker-compose -f docker-compose.simple.yml logs -f
```
* **Restart Service**:
```bash
docker-compose -f docker-compose.simple.yml restart
```
* **Stop Service**:
```bash
docker-compose -f docker-compose.simple.yml stop
```
* **Delete Service Container**:
```bash
docker-compose -f docker-compose.simple.yml down
```
#### Minimal Image Commands
* **View Logs**:
```bash
docker-compose -f docker-compose.minimal.yml logs -f
```
* **Restart Service**:
```bash
docker-compose -f docker-compose.minimal.yml restart
```
* **Stop Service**:
```bash
docker-compose -f docker-compose.minimal.yml stop
```
* **Delete Service Container**:
```bash
docker-compose -f docker-compose.minimal.yml down
```
### Domain Name Configuration and Development Instructions
#### Domain Name Configuration
When using a reverse proxy (such as nginx), you can set a domain name to generate HTTPS-formatted image URLs:
1. **Configure Domain Name**: Set the domain name in the `.env` file
```bash
DOMAIN=https://tikz.yourdomain.com
```
2. **Restart Service**:
```bash
docker-compose -f docker-compose.minimal.yml restart
```
#### Development Hot Reload
For ease of development, all script files have been volume-mapped into the container:
- **Mapped Files**:
- `tikz_http_server.py` → `/app/tikz_http_server.py`
- `clean_images.py` → `/app/clean_images.py`
- `run.sh` → `/app/run.sh`
- **Hot Reload Process**:
1. Directly modify local files
2. Run `docker-compose -f docker-compose.minimal.yml restart`
3. It takes effect without rebuilding the image
#### CORS Support
Comprehensive CORS header support has been added to allow all origins to access image resources, resolving cross-domain loading issues.
