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-diris configured, automatically saves generated charts and returns a specially formatted response that clients can parse to display the image:```local_image /path/to/chart.svg ``` - Deterministic Output: Ensures identical inputs produce bit-identical SVG outputs.
Installation
Requires Python >= 3.11 and uv installed.
Local Installation (Development)
git clone <repository-url>
cd plot-mcp
uv sync
Install as a Global Tool
uv tool install .
Running the Server
Running from Source
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:
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:
{
"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:
```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:
- Detect the
```local_imagemarker - Extract the file path
- 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 for a complete demonstration of how this format works.
Available Tools
The LLM can invoke the following tools:
plot_line: Render continuous 2D lines.plot_scatter: Render discrete 2D points.plot_bar: Render categorical bar charts.plot_area: Render filled area under a curve.plot_histogram: Render 1D histograms.plot_box: Render box plots from raw values.plot_heatmap: Render 2D matrix as a color grid.plot_contour: Render 2D contour lines.plot_pie: Render circular pie and donut charts.
Chart Configuration
All tools accept a shared config object to customize the visual output:
{
"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