Plotnine

You can run a Plotnine MCP Server to generate publication-ready ggplot2-style graphics from natural language. This server connects to your AI assistants, letting you describe the visualization you want and have the server translate it into a plot built with plotnine, including multiple layers, themes, facets, and data sources.

How to use

Use an MCP client to send natural-language requests that describe the plot you want. You can request basic plots such as a scatter with a trend line, or more complex multi-layer visuals with facets, themes, and data transformations. Start by loading data from a file, URL, or inline data, specify aesthetics like x, y, color, and then choose geometries (e.g., points, lines, bars). The server will return a plot object and can save outputs in PNG, PDF, or SVG formats with defined size and DPI. You can preview the data before plotting, apply transformations, and export or reuse plot configurations as JSON.

How to install

# Prerequisites
- Python (recommended via an environment manager)
- pip

# Step 1: Install the package in editable mode
pip install -e .

# Optional full functionality (Parquet and Excel support)
pip install -e ".[full]"

# Step 2: Find the MCP command path
which plotnine-mcp

Configuration and usage notes

Configure your MCP client to connect to the local Plotnine MCP server. You can run the MCP server directly and reference its command in your client settings. Examples show two common options: using the direct executable path to the server entry point, or invoking the server via Python’s module interface.

Examples of client configuration shown in practice include specifying the command and optional arguments to launch the server. You can either point to the Plotnine MCP executable or use the Python module approach to start the server.

Additional sections

Data sources accepted by the server include files (CSV, JSON, Parquet, Excel), URLs, or inline JSON data. Output formats supported are PNG, PDF, and SVG with configurable width, height, and DPI. You can preview data, apply built-in data transformations (filter, group, summarize, sort, select, mutate, etc.), and use templates or suggestions to guide plot type selection. Theming and coordinate options allow you to control aesthetics, scales, facets, and coordinate systems. You can export and import plot configurations as JSON for reuse.

If you need help diagnosing issues, ensure your data column names used in aesthetics exist in the data and that you provide required aesthetics for chosen geometries. For missing dependencies or format support, install with the recommended extra features using the full installation command shown above.

Troubleshooting

Module not found errors usually indicate the package isn’t installed in the active environment. Reinstall in editable mode and verify the path to the MCP command. For data file access issues, use absolute paths or paths relative to where your MCP client runs. If a plot doesn’t render, check that your data columns match the aesthetics and that you provided required values for the chosen geometry.

Development notes

Commands shown include building and starting steps for the MCP server. If you need to adjust or extend tooling, you can apply standard Python packaging and environment management practices to ensure reproducible server behavior.

Available tools

create_plot

Create a plotnine visualization with full customization by specifying data source, aesthetics, and geometry, along with optional scales, theme, facets, labels, and output configuration.

list_geom_types

List all available geometry types with descriptions to help you choose the right geometry for your data.

preview_data

Preview and inspect data before plotting, returning dataset shape, column types, first rows, statistics, and missing values.

list_plot_templates

List all predefined plot templates such as time_series, scatter_with_trend, distribution_comparison, and more.

create_plot_from_template

Create a plot using a predefined template, with data, aesthetics, optional labels, output, and overrides.

suggest_plot_templates

AI-powered recommendations for plot types based on data column types and a specified goal.

list_themes

List available themes for styling plots, with customization options.

list_color_palettes

List color palettes across several categories to suit different visualization needs.

export_plot_config

Export a plot configuration to JSON for reuse and sharing.

import_plot_config

Import a saved plot configuration and apply overrides as needed.

batch_create_plots

Create multiple plots in one operation, enabling batch visualizations across datasets or configurations.