plotly-mcp-cursor by arshlibruh - MCP Server

Plotly MCP Server - Implementation Plan

Project Overview

Goal: Graph Objects-only Plotly MCP server for Cursor
Output: HTML visualizations from natural language
Control: Minute-level customization of all chart elements
Scope: Complete coverage of 50+ Plotly trace types

Phase 1 Status ✅

Foundation Complete:

✅ MCP server with FastMCP framework (SDK 1.2.0+)
✅ Project structure for 49 trace types
✅ 5 basic trace builders (scatter, bar, line, pie, histogram)
✅ Figure assembly system
✅ Layout controllers (axes, styling)
✅ Sample data generation for testing
✅ Cursor integration ready

Quick Start

1. Install Dependencies

With UV (recommended):

# Install UV if you havent already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup project
cd /Users/arshad/Desktop/personal/code/plotly-mcp-claude
uv sync

With pip:

pip install -r requirements.txt

2. Run the MCP Server

cd src
python server.py

3. Add to Cursor MCP Settings

Add this to your Cursor MCP configuration:

{
  "mcpServers": {
    "plotly-mcp": {
      "command": "python",
      "args": ["/Users/arshad/Desktop/personal/code/plotly-mcp-claude/src/server.py"]
    }
  }
}

Available Tools (Phase 1)

Basic Trace Builders

create_scatter_plot - Scatter plots with markers, lines, or both
create_bar_chart - Vertical/horizontal bar charts with text labels
create_line_chart - Line charts with styling and fill options
create_pie_chart - Pie/donut charts with custom colors
create_histogram - Histograms with binning and normalization

Utility Tools

create_multi_trace_figure - Initialize figures for multiple traces
generate_sample_data - Create test data (linear, sine, random, categories)

Usage Examples

Scatter Plot

create_scatter_plot(
    x_data=[1, 2, 3, 4, 5],
    y_data=[2, 4, 1, 5, 3],
    colors="red",
    sizes=15,
    mode="markers+lines",
    name="My Data"
)

Bar Chart

create_bar_chart(
    x_data=["A", "B", "C", "D"],
    y_data=[20, 14, 23, 25],
    colors="blue",
    orientation="v",
    text=["20", "14", "23", "25"],
    name="Sales Data"
)

Pie Chart

create_pie_chart(
    labels=["Apple", "Orange", "Banana"],
    values=[30, 25, 45],
    hole=0.3,  # Donut chart
    textinfo="label+percent"
)

Generate Test Data

generate_sample_data(
    data_type="sine",
    size=100,
    noise=0.1
)

Architecture

plotly-mcp-claude/
├── src/
│   ├── server.py              # Main MCP server (FastMCP)
│   ├── traces/                # All trace builders (5/49 complete)
│   │   └── basic/            # Phase 1: scatter, bar, line, pie, histogram
│   ├── layouts/              # Layout controllers
│   │   ├── axes.py           # X/Y/Z axis configuration
│   │   └── styling.py        # Colors, fonts, margins, legends
│   ├── assembly/             # Figure building
│   │   └── builder.py        # Combine traces + layout
│   └── [themes/, nlp/]       # Future phases
├── data/                     # Sample datasets (future)
├── examples/                 # Usage examples (future)
├── tests/                    # Unit tests (future)
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Project configuration
└── README.md                # This file

Complete Plotly Trace Types (Planned)

Phase 1 ✅ (5/49)

Basic Charts: scatter ✅, bar ✅, line ✅, pie ✅, histogram ✅

Phase 2 📋 (15 more types)

Statistical Charts: box, violin, heatmap, contour, splom, parcoords, parcats, histogram2d
3D Charts: scatter3d, surface, mesh3d, volume, isosurface, cone, streamtube

Phase 3 📋 (15 more types)

Geographic Charts: choropleth, choroplethmap, choroplethmapbox, scattergeo, scattermap, scattermapbox, densitymap, densitymapbox
Financial Charts: candlestick, ohlc, waterfall
Hierarchical Charts: treemap, sunburst, icicle, sankey

Phase 4 📋 (14 more types)

Polar & Coordinates: scatterpolar, scatterpolargl, scattersmith, scatterternary, carpet, scattercarpet
Specialized Charts: funnel, funnelarea, indicator, image, table
Additional: barpolar, histogram2dcontour, contourcarpet

Total: 49 trace builders planned

Implementation Timeline

Phase 1 ✅ Foundation (5 basic traces) - COMPLETE
Phase 2 🚧 Statistical & 3D traces (15 more types)
Phase 3 📋 Geographic & Financial traces (15 more types)
Phase 4 📋 Remaining traces & complete layout (14 more types)
Phase 5 📋 Theming system (sci-fi, corporate, dark themes)
Phase 6 📋 Natural language interface

Technical Details

MCP Server Features

Built with MCP Python SDK 1.2.0+
FastMCP framework for easy tool definition
Async/await pattern throughout
Type hints for all parameters
Error handling with detailed messages
Logging for debugging

Chart Features

HTML output with embedded Plotly.js
Interactive charts (zoom, pan, hover)
Responsive design (800x600 default)
Professional styling (plotly_white theme)
Full customization of all visual elements

Testing

Each trace type returns complete HTML that can be:

Viewed directly in browser
Embedded in applications
Displayed in Cursor/Claude interface

Next Steps for Phase 2

Ready to add Statistical & 3D traces:

Box plots - quartile visualization
Violin plots - distribution shape
Heatmaps - 2D data correlation
3D scatter - three-dimensional points
Surface plots - 3D mathematical functions

Contributing

The modular architecture makes it easy to add new trace types:

Create trace builder in src/traces/{category}/
Add tool decorator in src/server.py
Test with sample data
Update documentation

Requirements

Python 3.10+
MCP Python SDK 1.2.0+
Plotly 5.0+
Modern browser for viewing charts

Phase 1 Complete - 5/49 trace types implemented Ready for Phase 2: Statistical & 3D visualization

Built with ❤️ for the Claude ecosystem