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:

  ```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)

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:

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 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:

{
  "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