Supports containerized deployment of the MCP plots server with configurable environment variables for chart settings and server configuration
Generates Mermaid diagrams for data visualization, providing instant chart rendering with support for line, bar, pie, funnel, gauge, and other chart types in Mermaid format
Distributes the MCP plots server package through PyPI for easy installation and dependency management
Plots MCP Server
A lightweight Model Context Protocol (MCP) server for data visualization. It exposes tools to render charts (line, bar, pie, scatter, heatmap, etc.) from tabular data and returns MCP-compatible image/text content.
Why MCP Plots?
- Instant, visual-first charts using Mermaid (renders directly in MCP clients like Cursor) 
- Simple prompts to generate charts from plain data 
- Zero-setup options via uvx, or install from PyPI/Docker 
- Flexible output formats: mermaid (default), PNG image, or text 
Quick Usage
- Ask your MCP client: "Create a bar chart showing sales: A=100, B=150, C=80" 
- Default output is Mermaid, so diagrams render instantly in Cursor 
Quick Start
PyPI Installation (Recommended)
For Cursor Users
- Install the package: - pip install mcp-plots
- Add to your Cursor MCP config ( - ~/.cursor/mcp.json):{ "mcpServers": { "plots": { "command": "mcp-plots", "args": ["--transport", "stdio"] } } }- Alternative (zero-install via uvx + PyPI): { "mcpServers": { "plots": { "command": "uvx", "args": ["mcp-plots", "--transport", "stdio"] } } }
- Restart Cursor 
- Ask: "Create a bar chart showing sales: A=100, B=150, C=80" 
Development Installation
Documentation → | Quick Start → | API Reference →
MCP Registry
This server is published under the MCP registry identifier io.github.MR901/mcp-plots. You can discover/verify it via the official registry API:
Registry metadata for this project is tracked in server.json.
Install with Smithery
This repository includes a smithery.yaml for easy setup with Smithery.
- File: - smithery.yaml
Example install using the Smithery CLI (adjust --client as needed, e.g. cursor, claude):
After installation, your MCP client should be able to start the server over stdio using the command defined in smithery.yaml.
Project layout
Requirements
- Python 3.10+ 
- See - requirements.txt
Setup Routes
uvx (Recommended)
The easiest way to run the MCP server without managing Python environments:
Why uvx?
- No Environment Management: Automatically handles Python dependencies 
- Isolated Execution: Runs in its own virtual environment 
- Always Latest: Pulls fresh code from repository 
- Zero Setup: Works immediately without pip install 
- Cross-Platform: Same command works on Windows, macOS, Linux 
PyPI (Traditional Installation)
- Install dependencies 
- Run the server (HTTP transport, default port 8000) 
- Run with stdio (for MCP clients that spawn processes) 
Local Development (from source)
Docker
Environment variables (optional):
- MCP_TRANSPORT(streamable-http|stdio)
- MCP_HOST(default 0.0.0.0)
- MCP_PORT(default 8000)
- LOG_LEVEL(default INFO)
Tools
- list_chart_types()→ returns available chart types
- list_themes()→ returns available themes
- suggest_fields(sample_rows)→ suggests field roles based on data samples
- render_chart(chart_type, data, field_map, config_overrides?, options?, output_format?)→ returns MCP content
- generate_test_image()→ generates a test image (red circle) to verify MCP image support
Cursor Integration
This MCP server is fully compatible with Cursor's image support! When you use the render_chart tool:
- Charts appear directly in chat - No need to save files or open separate windows 
- AI can analyze your charts - Vision-enabled models can discuss and interpret your visualizations 
- Perfect MCP format - Uses the exact base64 PNG format that Cursor expects 
The server returns images in the MCP format Cursor requires:
Example call (pseudo):
Return shape (PNG):
Configuration
The server can be configured via environment variables or command line arguments:
Server Settings
- MCP_TRANSPORT- Transport type:- streamable-httpor- stdio(default:- streamable-http)
- MCP_HOST- Host address (default:- 0.0.0.0)
- MCP_PORT- Port number (default:- 8000)
- LOG_LEVEL- Logging level:- DEBUG,- INFO,- WARNING,- ERROR,- CRITICAL(default:- INFO)
- MCP_DEBUG- Enable debug mode:- trueor- false(default:- false)
Chart Settings
- CHART_DEFAULT_WIDTH- Default chart width in pixels (default:- 800)
- CHART_DEFAULT_HEIGHT- Default chart height in pixels (default:- 600)
- CHART_DEFAULT_DPI- Default chart DPI (default:- 100)
- CHART_MAX_DATA_POINTS- Maximum data points per chart (default:- 10000)
Command Line Usage
With uvx (recommended):
Traditional Python:
Docker
Build image:
Run container with custom configuration:
Cursor MCP Integration
Quick Setup for Cursor
The Plots MCP Server is designed to work seamlessly with Cursor's MCP support. Here's how to integrate it:
1. Add to Cursor's MCP Configuration
Add this to your Cursor MCP configuration file (~/.cursor/mcp.json or similar):
2. Alternative: HTTP Transport
For HTTP-based integration:
3. Local Development Setup
For local development (if you have the code cloned):
4. Verify Integration
After adding the configuration:
- Restart Cursor 
- Check MCP connection in Cursor's MCP panel 
- Test with a simple chart: Create a bar chart showing sales data: A=100, B=150, C=80
MERMAID-First Approach
This server prioritizes MERMAID output by default because:
- ✅ Renders instantly in Cursor - No external viewers needed 
- ✅ Interactive - Cursor can analyze and discuss the diagrams 
- ✅ Lightweight - Fast generation and display 
- ✅ Scalable - Vector-based, works at any zoom level 
Chart Types with Native MERMAID Support:
- line,- bar,- pie,- area→- xychart-betaformat
- histogram→- xychart-betawith automatic binning
- funnel→ Styled flowchart with color gradients
- gauge→ Flowchart with color-coded value indicators
- sankey→ Flow diagrams with source/target styling
Available Tools
render_chart
Main chart generation tool with MERMAID-first approach.
Parameters:
- chart_type- Chart type (- line,- bar,- pie,- scatter,- heatmap, etc.)
- data- List of data objects
- field_map- Field mappings (- x_field,- y_field,- category_field, etc.)
- config_overrides- Chart configuration overrides
- output_format- Output format (- mermaid[default],- mcp_image,- mcp_text)
Special Modes:
- chart_type="help"- Show available chart types and themes
- chart_type="suggest"- Analyze data and suggest field mappings
configure_preferences
Interactive configuration tool for setting user preferences.
Parameters:
- output_format- Default output format (- mermaid,- mcp_image,- mcp_text)
- theme- Default theme (- default,- dark,- seaborn,- minimal)
- chart_width- Default chart width in pixels
- chart_height- Default chart height in pixels
- reset_to_defaults- Reset all preferences to system defaults
Features:
- Persistent Settings - Saved to - ~/.plots_mcp_config.json
- Live Preview - Shows sample chart with current settings 
- Override Support - Use - config_overridesfor one-off changes
Documentation
Additional Resources
- Complete Documentation - Technical documentation hub 
- Quick Start - 5-minute setup guide 
- Integration Guide - MCP client setup and configuration 
- API Reference - Complete tool specifications and examples 
- Advanced Guide - Architecture, deployment, and development 
- Sample Prompts - Ready-to-use testing examples 
Chart Examples
Basic Bar Chart:
Time Series Line Chart:
Funnel Chart:
🔧 Configuration
Environment Variables
- MCP_TRANSPORT- Transport type (- streamable-http|- stdio)
- MCP_HOST- Host address (default:- 0.0.0.0)
- MCP_PORT- Port number (default:- 8000)
- LOG_LEVEL- Logging level (default:- INFO)
- MCP_DEBUG- Enable debug mode (- true|- false)
- CHART_DEFAULT_WIDTH- Default chart width in pixels (default:- 800)
- CHART_DEFAULT_HEIGHT- Default chart height in pixels (default:- 600)
- CHART_DEFAULT_DPI- Default chart DPI (default:- 100)
- CHART_MAX_DATA_POINTS- Maximum data points per chart (default:- 10000)
User Preferences
Personal preferences are stored in ~/.plots_mcp_config.json:
🚀 Advanced Usage
Custom Themes
Available themes: default, dark, seaborn, minimal, whitegrid, darkgrid, ticks
High-Resolution Charts
Performance Optimization
- Use - max_data_pointsto limit large datasets
- MERMAID output is fastest for quick visualization 
- PNG output for high-quality static images 
- SVG output for scalable vector graphics 
🐛 Troubleshooting
Common Issues
Issue: Charts not rendering in Cursor
- Solution: Ensure - output_format="mermaid"(default)
- Check: MCP server connection in Cursor 
Issue: uvx command not found
- Solution: Install uv: - curl -LsSf https://astral.sh/uv/install.sh | sh
Issue: Port already in use
- Solution: Use different port: - --port 8001
Issue: Large datasets slow
- Solution: Sample data or increase - --max-data-points
Debug Mode
📝 Notes
- Matplotlib runs headless (Agg backend) in the container 
- For large datasets, sample your data for responsiveness 
- Chart defaults can be overridden per-request via - config_overrides
- MERMAID charts render instantly in Cursor for the best user experience 
- User preferences persist across sessions and apply to all charts by default 
A MCP server for data visualization. It exposes tools to render charts (line, bar, pie, scatter, heatmap, etc.) from data and returns plots as either image/text/mermaid diagram.