plotnine

Plotnine MCP Server exposes a Python-based interface that lets AI assistants generate complex ggplot2-style visualizations using plotnine. It supports a rich grammar of graphics workflow including aesthetics, geometries, scales, themes, facets, coordinates, and statistical transforms, with additional smart features such as plot templates, data previews, and AI-driven template suggestions. Core tools allow you to create multi-layer plots, list all geometry types, preview datasets, and export configurations. You can also generate plots from predefined templates, customize output formats (PNG, PDF, SVG) and sizes, and apply chained data transformations prior to plotting. Use the available tools to iterate quickly from natural language prompts to publication-quality visuals, with helpful error messages and suggestions when column names or geometry types are misspecified.

Typical usage flow:

• Prepare or load your data source (CSV, JSON, Parquet, Excel, URL, or inline JSON).
• Choose a geometry or multiple geoms, map aesthetics, and specify any scales, themes, and facets.
• Optionally preview the data to confirm column types and values.
• Generate the plot with create_plot, or select a predefined template with create_plot_from_template or list_plot_templates to bootstrap common patterns like time_series or scatter_with_trend.
• Output the visualization in your preferred format and size, and export the configuration for reuse.

Available tools include: create_plot, list_geom_types, preview_data, list_plot_templates, create_plot_from_template, suggest_plot_templates, list_themes, list_color_palettes, and export_plot_config. Each tool accepts structured data_source configurations and supports optional parameters for customization and output control.

Prerequisites:

• Python 3.8+ (recommended) with pip
• Git (for cloning the repository)

1. Clone the repository

git clone https://github.com/Fervoyush/plotnine-mcp.git
cd plotnine-mcp

2. Install the package in editable mode (for development)

pip install -e .

3. Install full extras (parquet and Excel support) if you need those formats

pip install -e ".[full]"

4. Run the MCP server locally (example)

python -m plotnine_mcp.server

5. Verify installation by listing available commands or starting with basic plots via your MCP client configuration.

Tips and common considerations:

• Data sources: You can load data from files (CSV, JSON, Parquet, Excel), URLs, or inline JSON. Ensure column names referenced in aesthetics exist in the data.
• Output formats: PNG, PDF, and SVG are supported with configurable dimensions and DPI. Adjust output accordingly for publication needs.
• Templates and AI suggestions: Use list_plot_templates to discover prebuilt patterns (e.g., time_series, scatter_with_trend, distribution_comparison). Use suggest_plot_templates to get AI-driven recommendations based on your data types and goals.
• Data transformations: Use the transforms capability to filter, group_summarize, mutate, and more, then plot the transformed dataset.
• Environment variables: If your deployment requires custom configuration (e.g., data paths, authentication for data sources), pass them via standard environment variables in your hosting environment.
• Debugging: If a column name or geom type is misspelled, the Smart Error Messages feature provides fuzzy-matching hints to correct typos.