io.github.MR901/plots-mcp

Official

by MR901 · Python

MCP server for data visualization with Mermaid charts.

Create and visualize data with Mermaid chart generation.

Topics

ready-to-use

README.md15 KBView on GitHub

<div align="center"> <h1>Plots MCP Server</h1>

<a href="https://glama.ai/mcp/servers/@MR901/mcp-plots"> <img width="285" height="150" src="https://glama.ai/mcp/servers/@MR901/mcp-plots/badge" /> </a> </div> <br> A Model Context Protocol (MCP) server for data visualization. It exposes tools to render charts (line, bar, pie, scatter, heatmap, etc.) from data and returns the plot as image/base64 text/mermaid diagram.

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)

bash

pip install mcp-plots
mcp-plots  # Start the server

For Cursor Users

Install the package: pip install mcp-plots

Add to your Cursor MCP config (~/.cursor/mcp.json):

json

{
  "mcpServers": {
    "plots": {
      "command": "mcp-plots",
      "args": ["--transport", "stdio"]
    }
  }
}

Alternative (zero-install via uvx + PyPI):

json

{
  "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

bash

uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

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:

bash

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.MR901/mcp-plots"

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
Docs: https://smithery.ai/docs/config#smitheryyaml

Example install using the Smithery CLI (adjust --client as needed, e.g. cursor, claude):

bash

npx -y @smithery/cli install \
  https://raw.githubusercontent.com/mr901/mcp-plots/main/smithery.yaml \
  --client cursor

After installation, your MCP client should be able to start the server over stdio using the command defined in smithery.yaml.

Project layout

code

src/
  app/                # Server construction and runtime
    server.py
  capabilities/       # MCP tools and prompts
    tools.py
    prompts.py
  visualization/      # Plotting engines and configurations
    chart_config.py
    generator.py

Requirements

Python 3.10+
See requirements.txt

Setup Routes

uvx (Recommended)

The easiest way to run the MCP server without managing Python environments:

bash

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

# Or install and run the command
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots

# With custom options
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG

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

bash

pip install -r requirements.txt

Run the server (HTTP transport, default port 8000)

bash

python -m src --transport streamable-http --host 0.0.0.0 --port 8000 --log-level INFO

Run with stdio (for MCP clients that spawn processes)

bash

python -m src --transport stdio

Local Development (from source)

bash

git clone https://github.com/mr901/mcp-plots.git
cd mcp-plots
pip install -e .
python -m src --transport stdio --log-level DEBUG

Docker

bash

docker build -t mcp-plots .
docker run -p 8000:8000 mcp-plots

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:

json

{
  "content": [
    {
      "type": "image", 
      "data": "<base64-encoded-png>",
      "mimeType": "image/png"
    }
  ]
}

Example call (pseudo):

code

render_chart(
  chart_type="bar",
  data=[{"category":"A","value":10},{"category":"B","value":20}],
  field_map={"category_field":"category","value_field":"value"},
  config_overrides={"title":"Example Bar","width":800,"height":600,"output_format":"MCP_IMAGE"}
)

Return shape (PNG):

code

{
  "status": "success",
  "content": [{"type":"image","data":"<base64>","mimeType":"image/png"}]
}

Configuration

The server can be configured via environment variables or command line arguments:

Server Settings

MCP_TRANSPORT - Transport type: streamable-http or 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: true or 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):

bash

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --help

# Examples:
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --chart-width 1200 --chart-height 800

Traditional Python:

bash

python -m src --help

# Examples:
python -m src --transport streamable-http --host 0.0.0.0 --port 8000
python -m src --log-level DEBUG --chart-width 1200 --chart-height 800

Docker

Build image:

code

docker build -t mcp-plots .

Run container with custom configuration:

bash

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e LOG_LEVEL=INFO \
  -e CHART_DEFAULT_WIDTH=1000 \
  -e CHART_DEFAULT_HEIGHT=700 \
  -e CHART_DEFAULT_DPI=150 \
  -e CHART_MAX_DATA_POINTS=5000 \
  mcp-plots

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):

json

{
  "mcpServers": {
    "plots": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/mr901/mcp-plots.git@main",
        "mcp-plots",
        "--transport", 
        "stdio"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "CHART_DEFAULT_WIDTH": "800",
        "CHART_DEFAULT_HEIGHT": "600"
      }
    }
  }
}

2. Alternative: HTTP Transport

For HTTP-based integration:

json

{
  "mcpServers": {
    "plots-http": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/mr901/mcp-plots.git@main", 
        "mcp-plots",
        "--transport", 
        "streamable-http",
        "--host", 
        "127.0.0.1",
        "--port", 
        "8000"
      ]
    }
  }
}

3. Local Development Setup

For local development (if you have the code cloned):

json

{
  "mcpServers": {
    "plots-dev": {
      "command": "python",
      "args": ["-m", "src", "--transport", "stdio"],
      "cwd": "/path/to/mcp-plots",
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

4. Verify Integration

After adding the configuration:

Restart Cursor
Check MCP connection in Cursor's MCP panel

Test with a simple chart:

code

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-beta format
histogram → xychart-beta with 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_overrides for 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:

json

{
  "chart_type": "bar",
  "data": [
    {"category": "Sales", "value": 120},
    {"category": "Marketing", "value": 80},
    {"category": "Support", "value": 60}
  ],
  "field_map": {
    "category_field": "category", 
    "value_field": "value"
  }
}

Time Series Line Chart:

json

{
  "chart_type": "line",
  "data": [
    {"date": "2024-01", "revenue": 1000},
    {"date": "2024-02", "revenue": 1200},
    {"date": "2024-03", "revenue": 1100}
  ],
  "field_map": {
    "x_field": "date",
    "y_field": "revenue"
  }
}

Funnel Chart:

json

{
  "chart_type": "funnel",
  "data": [
    {"stage": "Awareness", "value": 1000},
    {"stage": "Interest", "value": 500}, 
    {"stage": "Purchase", "value": 100}
  ],
  "field_map": {
    "category_field": "stage",
    "value_field": "value"
  }
}

🔧 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:

json

{
  "defaults": {
    "output_format": "mermaid",
    "theme": "default",
    "chart_width": 800,
    "chart_height": 600
  },
  "user_preferences": {
    "output_format": "mcp_image",
    "theme": "dark"
  }
}

🚀 Advanced Usage

Custom Themes

Available themes: default, dark, seaborn, minimal, whitegrid, darkgrid, ticks

High-Resolution Charts

bash

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \
  --chart-width 1920 \
  --chart-height 1080 \
  --chart-dpi 300

Performance Optimization

Use max_data_points to 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

bash

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \
  --debug \
  --log-level DEBUG

📝 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

Install

claude_desktop_config.json

{
  "mcpServers": {
    "plots-mcp": {
      "command": "uvx",
      "args": [
        "mcp-plots"
      ]
    }
  }
}