{"id":32848724,"url":"https://github.com/fervoyush/plotnine-mcp","last_synced_at":"2025-11-12T14:00:43.300Z","repository":{"id":322793043,"uuid":"1090865053","full_name":"Fervoyush/plotnine-mcp","owner":"Fervoyush","description":"MCP server bringing ggplot2's grammar of graphics to Python via plotnine. Create publication-quality statistical visualizations through natural language with AI assisted IDEs like Claude-Code, Cursor and VSCode","archived":false,"fork":false,"pushed_at":"2025-11-06T10:38:22.000Z","size":36,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T12:08:41.646Z","etag":null,"topics":["ai","claude-code","cursor-ai","data-visualization","ggplot2","grammar-of-graphics","mcp","model-context-protocol","plotnine","python3","statistics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fervoyush.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T08:39:48.000Z","updated_at":"2025-11-06T10:38:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Fervoyush/plotnine-mcp","commit_stats":null,"previous_names":["fervoyush/plotnine-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Fervoyush/plotnine-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fervoyush%2Fplotnine-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fervoyush%2Fplotnine-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fervoyush%2Fplotnine-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fervoyush%2Fplotnine-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fervoyush","download_url":"https://codeload.github.com/Fervoyush/plotnine-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fervoyush%2Fplotnine-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284045913,"owners_count":26938122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-12T02:00:06.336Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","cursor-ai","data-visualization","ggplot2","grammar-of-graphics","mcp","model-context-protocol","plotnine","python3","statistics"],"created_at":"2025-11-08T10:00:46.070Z","updated_at":"2025-11-12T14:00:43.257Z","avatar_url":"https://github.com/Fervoyush.png","language":"Python","readme":"# Plotnine MCP Server\n\n\u003e **A Model Context Protocol (MCP) server that brings ggplot2's grammar of graphics to Python through plotnine, enabling AI-powered data visualization via natural language.**\n\nCreate publication-quality statistical graphics through chat using plotnine's Python implementation of R's beloved ggplot2. This modular MCP server allows Claude and other AI assistants to generate highly customizable visualizations by composing layers through the grammar of graphics paradigm.\n\n\u003ca href=\"https://glama.ai/mcp/servers/@Fervoyush/plotnine-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@Fervoyush/plotnine-mcp/badge\" alt=\"Plotnine Server MCP server\" /\u003e\n\u003c/a\u003e\n\n## Features\n\n### Core Visualization\n- **🎨 Multi-Layer Plots**: Combine multiple geometries in a single plot (scatter + trend lines, boxplots + jitter, etc.)\n- **Grammar of Graphics**: Compose plots using aesthetics, geometries, scales, themes, facets, and coordinates\n- **20+ Geometry Types**: Points, lines, bars, histograms, boxplots, violins, and more\n- **Multiple Data Sources**: Load data from files (CSV, JSON, Parquet, Excel), URLs, or inline JSON\n- **Multiple Output Formats**: PNG, PDF, SVG with configurable dimensions and DPI\n\n### Smart Features (NEW!)\n- **📋 9 Plot Templates**: Pre-configured templates for common patterns (time series, scatter with trend, distribution comparison, etc.)\n- **🤖 AI Template Suggestions**: Analyzes your data and recommends appropriate plot types\n- **🎨 21 Color Palettes**: Colorblind-safe, scientific, categorical, corporate, sequential, and diverging palettes\n- **📊 Data Preview**: Inspect data before plotting with comprehensive summaries\n- **🎯 Smart Error Messages**: Fuzzy matching suggests corrections for typos in column names, geom types, and themes\n- **💾 Config Export/Import**: Save and reuse plot configurations as JSON files\n\n### Data Manipulation (NEW!)\n- **🔄 12 Data Transformations**: filter, group_summarize, sort, select, rename, mutate, drop_na, fill_na, sample, unique, rolling, pivot\n- **⚡ Batch Processing**: Create multiple plots in one operation\n- **🔗 Chained Transforms**: Apply multiple transformations in sequence\n\n### Theming \u0026 Customization\n- **Flexible Theming**: Built-in themes with extensive customization options\n- **Statistical Transformations**: Add smoothing, binning, density estimation, and summaries\n- **Faceting**: Split plots by categorical variables using wrap or grid layouts\n\n## Installation\n\n### 1. Clone or download this repository\n\n```bash\ncd plotnine-mcp\n```\n\n### 2. Install dependencies\n\nUsing pip:\n```bash\npip install -e .\n```\n\nFor full functionality (parquet and Excel support):\n```bash\npip install -e \".[full]\"\n```\n\n### 3. Configure Your MCP Client\n\n#### Claude Desktop\n\nAdd the server to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"plotnine\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"plotnine_mcp.server\"]\n    }\n  }\n}\n```\n\nIf you installed in a virtual environment, use the full path to python:\n```json\n{\n  \"mcpServers\": {\n    \"plotnine\": {\n      \"command\": \"/path/to/venv/bin/python\",\n      \"args\": [\"-m\", \"plotnine_mcp.server\"]\n    }\n  }\n}\n```\n\n#### Cursor\n\nAdd to your Cursor settings by opening the command palette (`Cmd/Ctrl+Shift+P`) and searching for \"Preferences: Open User Settings (JSON)\". Add:\n\n```json\n{\n  \"mcp.servers\": {\n    \"plotnine\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"plotnine_mcp.server\"]\n    }\n  }\n}\n```\n\nOr configure via `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"plotnine\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"plotnine_mcp.server\"]\n    }\n  }\n}\n```\n\n#### VSCode (with Cline/Roo-Cline)\n\nAdd to your VSCode MCP settings file:\n\n**macOS/Linux**: `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`\n\n**Windows**: `%APPDATA%\\Code\\User\\globalStorage\\rooveterinaryinc.roo-cline\\settings\\cline_mcp_settings.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"plotnine\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"plotnine_mcp.server\"]\n    }\n  }\n}\n```\n\nFor other MCP clients in VSCode, consult their specific documentation for MCP server configuration.\n\n### 4. Restart Your Application\n\nRestart Claude Desktop, Cursor, or VSCode for the changes to take effect. The plotnine MCP server should now be available!\n\n## Usage\n\n### Basic Example\n\n```\nCreate a scatter plot from data.csv with x=age and y=height\n```\n\n### Advanced Example\n\n```\nCreate a line plot from sales_data.csv showing:\n- x: date, y: revenue, color by region\n- Use a minimal theme with figure size 12x6\n- Add a smooth trend line\n- Facet by product category\n- Label the plot \"Q4 Sales Performance\"\n- Save as PDF\n```\n\n## Available Tools (11 Total)\n\n### Core Tools\n\n#### create_plot\n\nCreate a plotnine visualization with full customization.\n\n**Required Parameters:**\n- `data_source`: Data source configuration\n- `aes`: Aesthetic mappings (column names)\n- `geom` or `geoms`: Geometry specification(s)\n\n**Optional Parameters:**\n- `scales`: Array of scale configurations\n- `theme`: Theme configuration\n- `facets`: Faceting configuration\n- `labels`: Plot labels (title, x, y, caption, subtitle)\n- `coords`: Coordinate system configuration\n- `stats`: Statistical transformations\n- `transforms`: Data transformations (NEW!)\n- `output`: Output configuration (format, size, DPI, directory)\n\n#### list_geom_types\n\nList all 20+ available geometry types with descriptions.\n\n### Data Tools (NEW!)\n\n#### preview_data\n\nPreview and inspect data before creating plots. Returns dataset shape, column types, first rows, statistics, and missing values.\n\n**Parameters:**\n- `data_source`: Data source configuration\n- `rows`: Number of rows to preview (default: 5)\n\n### Template Tools (NEW!)\n\n#### list_plot_templates\n\nList all 9 available plot templates with descriptions:\n- time_series\n- scatter_with_trend\n- distribution_comparison\n- category_breakdown\n- correlation_heatmap\n- boxplot_comparison\n- multi_line\n- histogram_with_density\n- before_after\n\n#### create_plot_from_template\n\nCreate a plot using a predefined template. Just provide data and aesthetics; the template handles the rest.\n\n**Parameters:**\n- `template_name`: Name of the template\n- `data_source`: Data source configuration\n- `aes`: Aesthetic mappings\n- `labels`: Optional labels\n- `output`: Optional output config\n- `overrides`: Optional overrides for template settings\n\n#### suggest_plot_templates\n\nAnalyze your data and get AI-powered plot recommendations based on column types and optional goal.\n\n**Parameters:**\n- `data_source`: Data source to analyze\n- `goal`: Optional goal (e.g., \"compare distributions\", \"show trend\")\n\n### Style Tools (NEW!)\n\n#### list_themes\n\nList all available themes for plot styling with descriptions and customization options.\n\n#### list_color_palettes\n\nList 21 color palettes across 6 categories:\n- Colorblind-safe (3 palettes)\n- Scientific (4 palettes)\n- Categorical (4 palettes)\n- Corporate (3 palettes)\n- Sequential (4 palettes)\n- Diverging (3 palettes)\n\n**Parameters:**\n- `category`: Optional category filter\n\n### Configuration Tools\n\n#### export_plot_config\n\nExport plot configuration to JSON for reuse and sharing.\n\n**Parameters:**\n- `config`: The plot configuration to export\n- `filename`: Output filename\n- `directory`: Output directory (default: './plot_configs')\n\n#### import_plot_config\n\nImport and use a saved plot configuration with optional overrides.\n\n**Parameters:**\n- `config_path`: Path to saved configuration\n- `overrides`: Optional parameter overrides\n\n### Batch Tools (NEW!)\n\n#### batch_create_plots\n\nCreate multiple plots in one operation. Perfect for generating plots for all columns, pairwise comparisons, or different visualizations of the same data.\n\n**Parameters:**\n- `plots`: Array of plot configurations\n\n## Geometry Types\n\n- **point**: Scatter plot points\n- **line**: Line plot connecting points\n- **bar**: Bar chart (counts by default)\n- **col**: Column chart (identity stat)\n- **histogram**: Histogram of continuous data\n- **boxplot**: Box and whisker plot\n- **violin**: Violin plot for distributions\n- **area**: Filled area under line\n- **density**: Kernel density plot\n- **smooth**: Smoothed conditional means\n- **jitter**: Jittered points (reduces overplotting)\n- **tile**: Heatmap/tile plot\n- **text**: Text annotations\n- **errorbar**: Error bars\n- **hline/vline/abline**: Reference lines\n- **path**: Path connecting points in order\n- **polygon**: Filled polygon\n- **ribbon**: Ribbon for intervals\n\n## Examples\n\n### Simple Scatter Plot\n\n```json\n{\n  \"data_source\": {\n    \"type\": \"file\",\n    \"path\": \"./data/iris.csv\"\n  },\n  \"aes\": {\n    \"x\": \"sepal_length\",\n    \"y\": \"sepal_width\",\n    \"color\": \"species\"\n  },\n  \"geom\": {\n    \"type\": \"point\",\n    \"params\": {\"size\": 3, \"alpha\": 0.7}\n  }\n}\n```\n\n### Line Plot with Theme\n\n```json\n{\n  \"data_source\": {\n    \"type\": \"url\",\n    \"path\": \"https://example.com/timeseries.csv\"\n  },\n  \"aes\": {\n    \"x\": \"date\",\n    \"y\": \"value\",\n    \"color\": \"category\"\n  },\n  \"geom\": {\n    \"type\": \"line\",\n    \"params\": {\"size\": 1.5}\n  },\n  \"scales\": [\n    {\n      \"aesthetic\": \"x\",\n      \"type\": \"datetime\",\n      \"params\": {\"date_breaks\": \"1 month\"}\n    }\n  ],\n  \"theme\": {\n    \"base\": \"minimal\",\n    \"customizations\": {\n      \"figure_size\": [12, 6],\n      \"legend_position\": \"bottom\"\n    }\n  },\n  \"labels\": {\n    \"title\": \"Time Series Analysis\",\n    \"x\": \"Date\",\n    \"y\": \"Value\"\n  }\n}\n```\n\n### Faceted Boxplot\n\n```json\n{\n  \"data_source\": {\n    \"type\": \"inline\",\n    \"data\": [\n      {\"group\": \"A\", \"category\": \"X\", \"value\": 10},\n      {\"group\": \"A\", \"category\": \"Y\", \"value\": 15},\n      {\"group\": \"B\", \"category\": \"X\", \"value\": 12}\n    ]\n  },\n  \"aes\": {\n    \"x\": \"group\",\n    \"y\": \"value\",\n    \"fill\": \"group\"\n  },\n  \"geom\": {\n    \"type\": \"boxplot\"\n  },\n  \"facets\": {\n    \"type\": \"wrap\",\n    \"facets\": \"~ category\"\n  },\n  \"theme\": {\n    \"base\": \"bw\"\n  }\n}\n```\n\n### Multi-Layer Plot: Scatter + Smooth Trend\n\n**NEW!** Layer multiple geometries to create complex visualizations:\n\n```json\n{\n  \"data_source\": {\n    \"type\": \"file\",\n    \"path\": \"./data/measurements.csv\"\n  },\n  \"aes\": {\n    \"x\": \"time\",\n    \"y\": \"value\",\n    \"color\": \"sensor\"\n  },\n  \"geoms\": [\n    {\n      \"type\": \"point\",\n      \"params\": {\"size\": 2, \"alpha\": 0.6}\n    },\n    {\n      \"type\": \"smooth\",\n      \"params\": {\"method\": \"lm\", \"se\": false}\n    }\n  ],\n  \"theme\": {\n    \"base\": \"minimal\",\n    \"customizations\": {\"figure_size\": [12, 6]}\n  },\n  \"labels\": {\n    \"title\": \"Sensor Readings with Trend Lines\",\n    \"x\": \"Time\",\n    \"y\": \"Measurement\"\n  }\n}\n```\n\n### Boxplot with Jittered Points\n\nShow both distribution summary and individual data points:\n\n```json\n{\n  \"data_source\": {\n    \"type\": \"file\",\n    \"path\": \"./data/experiment.csv\"\n  },\n  \"aes\": {\n    \"x\": \"treatment\",\n    \"y\": \"response\",\n    \"fill\": \"treatment\"\n  },\n  \"geoms\": [\n    {\n      \"type\": \"boxplot\",\n      \"params\": {\"alpha\": 0.7}\n    },\n    {\n      \"type\": \"jitter\",\n      \"params\": {\"width\": 0.2, \"alpha\": 0.5, \"size\": 1}\n    }\n  ],\n  \"theme\": {\n    \"base\": \"bw\"\n  },\n  \"labels\": {\n    \"title\": \"Treatment Effects with Individual Observations\"\n  }\n}\n```\n\n## Chat Examples\n\nYou can create plots through natural language:\n\n**\"Create a histogram of the 'age' column from users.csv\"**\n\n**\"Make a scatter plot with smooth trend line showing price vs size, colored by category\"**\n\n**\"Plot a line chart from sales.csv with date on x-axis and revenue on y-axis, faceted by region, using a dark theme\"**\n\n**\"Create a violin plot comparing distributions of test scores across different schools\"**\n\n**\"Make a boxplot with individual points overlaid showing temperature by season\"**\n\n**\"Create a scatter plot with a linear trend line for each category, showing the relationship between hours studied and test scores\"**\n\n### Using New Tools\n\n**\"Preview the data from sales.csv before plotting\"**\n\n**\"What themes are available?\"**\n\n**\"Show me all available plot templates\"**\n\n**\"Suggest appropriate plot types for my data\"**\n\n**\"Create a time series plot using the template\"**\n\n**\"List color palettes in the scientific category\"**\n\n**\"Export this plot configuration so I can reuse it later\"**\n\n**\"Load the plot config from my_config.json and use it with a different dataset\"**\n\n**\"Create a plot from the saved configuration but change the theme to minimal\"**\n\n**\"Create plots for each category in my dataset\"** (batch processing)\n\n**\"Filter the data to show only active users, then create a histogram\"** (data transformations)\n\n## New Examples\n\n### Using Templates\n\nCreate a scatter plot with trend line using a template:\n\n```\n\"Use the scatter_with_trend template to plot height vs weight from my data\"\n```\n\nThis automatically creates a plot with:\n- Scatter points (with transparency)\n- Linear regression line\n- Confidence interval\n- Minimal theme\n\n### Using Color Palettes\n\n```\n\"Create a bar chart colored using the colorblind-safe Okabe-Ito palette\"\n```\n\n### Data Transformations\n\n```\n\"Filter sales data to show only Q4, group by region, sum the revenue, and create a bar chart\"\n```\n\nThis applies transformations before plotting:\n1. Filter: `\"quarter == 'Q4'\"`\n2. Group \u0026 summarize: by region, sum revenue\n3. Plot: bar chart of results\n\n### Batch Processing\n\n```\n\"Create histogram plots for all numeric columns in my dataset\"\n```\n\n## Configuration Options\n\n### Themes\n\nAvailable base themes:\n- `gray` (default)\n- `bw` (black and white)\n- `minimal`\n- `classic`\n- `dark`\n- `light`\n- `void`\n\n### Scale Types\n\n- **Positional**: continuous, discrete, log10, sqrt, datetime\n- **Color/Fill**: gradient, discrete, brewer\n\n### Coordinate Systems\n\n- `cartesian` (default)\n- `flip` (swap x and y)\n- `fixed` (fixed aspect ratio)\n- `trans` (transformed coordinates)\n\n## Output\n\nBy default, plots are saved to `./output` directory as PNG files with 300 DPI. You can customize:\n\n- **format**: png, pdf, svg\n- **filename**: Custom filename (auto-generated by default)\n- **width/height**: Dimensions in inches\n- **dpi**: Resolution for raster formats\n- **directory**: Output directory path\n\n## Troubleshooting\n\n### \"Module not found\" errors\n\nEnsure you've installed the package:\n```bash\npip install -e .\n```\n\n### Parquet/Excel support\n\nInstall optional dependencies:\n```bash\npip install -e \".[full]\"\n```\n\n### \"Cannot find data file\"\n\nUse absolute paths or paths relative to where Claude Desktop is running.\n\n### Plot not rendering\n\nCheck that:\n- Column names in `aes` match your data\n- Data types are appropriate for the geometry\n- Required aesthetics are provided (e.g., `x` and `y` for most geoms)\n\n## Development\n\n### Running tests\n```bash\npytest\n```\n\n### Code formatting\n```bash\nblack src/\nruff check src/\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue or submit a pull request.\n\n## Resources\n\n- [plotnine documentation](https://plotnine.readthedocs.io/)\n- [MCP specification](https://modelcontextprotocol.io/)\n- [Grammar of Graphics](https://ggplot2.tidyverse.org/)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffervoyush%2Fplotnine-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffervoyush%2Fplotnine-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffervoyush%2Fplotnine-mcp/lists"}