# PlotMCP Server
PlotMCP is a powerful Model Context Protocol (MCP) server designed to enable LLMs to generate high-quality SVG charts from structured data. It leverages `fastmcp` for the server infrastructure and `matplotlib` for consistent, precise chart rendering.
## Key Features
- **Pure SVG Rendering**: Generates static SVG format with no external JavaScript dependencies. Safe, portable, and easy to embed.
- **Multiple Plot Types**: Supports Line, Scatter, Bar, Area, Histogram, Box, Heatmap, Contour, and Pie charts.
- **Flexible Configuration**: Full control over titles, dimensions, margins, and axis properties (linear, log, and symlog scales).
- **Output Management**: When `--output-dir` is configured, automatically saves generated charts and returns a specially formatted response that clients can parse to display the image:
````markdown
```local_image
/path/to/chart.svg
```
````
This format allows clients to easily detect and render the generated images.
- **Deterministic Output**: Ensures identical inputs produce bit-identical SVG outputs.
## Installation
Requires Python >= 3.11 and `uv` installed.
### Local Installation (Development)
```bash
git clone <repository-url>
cd plot-mcp
uv sync
```
### Install as a Global Tool
```bash
uv tool install .
```
## Running the Server
### Running from Source
```bash
uv run plot-mcp --output-dir ./plots
```
### Running Remotely via GitHub (using `uvx`)
You can run the server directly from the GitHub repository without manual cloning:
```bash
uvx --from git+https://github.com/Nexo-Agent/plot-mcp plot-mcp --output-dir ./plots
```
_Note: Replace the URL with the actual repository location._
## CLI Configuration
The server supports the following command-line options:
- `--output-dir PATH`: Directory where generated SVG files will be saved. When set, tools return the file path instead of the raw SVG content.
- `--transport [stdio|sse|streamable-http]`: The communication protocol (default: `stdio`).
- `--port INTEGER`: The port for SSE or HTTP transport (default: 8000).
## Output Format
The server supports two output modes depending on whether `--output-dir` is configured:
### Without `--output-dir` (Default)
Tools return a `PlotOutput` object containing the raw SVG content:
```json
{
"svg": "<svg>...</svg>",
"width": 800,
"height": 400,
"viewBox": "0 0 800 400"
}
```
### With `--output-dir` (Recommended)
Tools save the SVG to a file and return a specially formatted string:
````markdown
```local_image
/absolute/path/to/chart.svg
```
````
This format is designed to be easily parsed by clients. When your client receives a response containing this pattern, it should:
1. Detect the ` ```local_image` marker
2. Extract the file path
3. Load and display the image from that path
This approach keeps the response lightweight and allows clients to handle image rendering efficiently.
**See [`examples/local_image_format.py`](examples/local_image_format.py) for a complete demonstration of how this format works.**
## Available Tools
The LLM can invoke the following tools:
1. `plot_line`: Render continuous 2D lines.
2. `plot_scatter`: Render discrete 2D points.
3. `plot_bar`: Render categorical bar charts.
4. `plot_area`: Render filled area under a curve.
5. `plot_histogram`: Render 1D histograms.
6. `plot_box`: Render box plots from raw values.
7. `plot_heatmap`: Render 2D matrix as a color grid.
8. `plot_contour`: Render 2D contour lines.
9. `plot_pie`: Render circular pie and donut charts.
## Chart Configuration
All tools accept a shared `config` object to customize the visual output:
```json
{
"title": "My Chart",
"width": 800,
"height": 400,
"margin": { "top": 40, "right": 20, "bottom": 40, "left": 50 },
"x_axis": { "label": "X Axis", "scale": "linear" },
"y_axis": { "label": "Y Axis", "scale": "log" }
}
```
## License
MIT
