PlotMCP Server

PlotMCP is a server that lets you generate high-quality SVG charts from structured data using a Model Context Protocol (MCP). It renders pure SVG for safe, portable images and supports multiple chart types with flexible configuration. You can run it locally or host it remotely, then connect your MCP client to request charts and receive either raw SVG or a path to a saved image.

How to use

You interact with PlotMCP by starting the local server or running it from a remote host and then sending chart requests from your MCP client. You can request any supported chart type (Line, Scatter, Bar, Area, Histogram, Box, Heatmap, Contour, Pie) with a shared configuration object that specifies the title, size, margins, and axis properties. If you enable an output directory, the server saves every generated chart as an SVG file and returns a lightweight reference to that image instead of the SVG content, making it easy to render images in your client.

Practical usage patterns include starting the server with an output directory to persist SVGs, and then requesting charts for dashboards, reports, or data explorations. The server produces deterministic SVGs, so the same input yields the same image every time.

How to install

Prerequisites you need before installing PlotMCP: Python 3.11 or newer and the uv tool installed.

Step 1: Install the runtime tool and set up the project environment.

Step 2: Install and run from source.

Step 3: Optional: install as a global tool for easier access.

Concrete commands you will run include cloning the repository, syncing dependencies with uv, and starting the server. Use the exact commands shown below.

# Local installation (development)
git clone <repository-url>
cd plot-mcp
uv sync

# Run from source with an output directory
uv run plot-mcp --output-dir ./plots

# Install as a global tool for easy access
uv tool install .

Additional setup and notes

If you prefer to run directly from the GitHub source without cloning, you can use the remote execution flow with uvx. This lets you run the MCP server from a repository reference.

Example commands to run from a remote source include starting via uvx with an output directory.

# Run remotely from the GitHub repository
uvx --from git+https://github.com/Nexo-Agent/plot-mcp plot-mcp --output-dir ./plots

Output behavior and formats

The server can return either the raw SVG content or a file path to a saved image depending on whether you configure an output directory.

Without an output directory you receive a PlotOutput object containing the SVG data and image dimensions.

With an output directory you get a compact local image reference that your client can render by loading the SVG from the indicated path.

`local_image
/absolute/path/to/chart.svg
`

Security and reliability notes

The SVGs are pure SVG with no external JavaScript dependencies, which helps ensure safe embedding in various environments.

The server aims for deterministic output, so the same inputs will produce identical SVG files across runs.

Available tools

plot_line

Render continuous 2D lines by supplying ordered data points to form a connected line.

plot_scatter

Render discrete 2D points to visualize individual observations or samples.

plot_bar

Render categorical bar charts to compare quantities across categories.

plot_area

Render filled area under a curve to emphasize magnitude over a range.

plot_histogram

Render 1D histograms to show the distribution of numeric data.

plot_box

Render box plots to summarize distribution statistics from raw values.

plot_heatmap

Render a 2D matrix as a color grid to reveal intensity patterns.

plot_contour

Render 2D contour lines to illustrate level sets of a scalar field.

plot_pie

Render circular pie and donut charts to show proportional composition.