Skip to main content
Glama

mcp-plots

by MR901
GitHub
Python
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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)

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

For Cursor Users

  1. Install the package: pip install mcp-plots

  2. 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"] } } }

  3. Restart Cursor

  4. Ask: "Create a bar chart showing sales: A=100, B=150, C=80"

Development Installation

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:

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.

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

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

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:

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

  1. Install dependencies

pip install -r requirements.txt

  1. Run the server (HTTP transport, default port 8000)

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

  1. Run with stdio (for MCP clients that spawn processes)

python -m src --transport stdio

Local Development (from source)

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

Docker

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:

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

Example call (pseudo):

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

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

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:

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:

docker build -t mcp-plots .

Run container with custom configuration:

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

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

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

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

  1. Restart Cursor

  2. Check MCP connection in Cursor's MCP panel

  3. 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-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

Chart Examples

Basic Bar Chart:

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

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

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

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

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

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

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Tools

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.

  1. Why MCP Plots?
    1. Quick Usage
      1. Quick Start
        1. PyPI Installation (Recommended)
        2. For Cursor Users
        3. Development Installation
      2. MCP Registry
        1. Install with Smithery
          1. Project layout
            1. Requirements
              1. Setup Routes
                1. uvx (Recommended)
                2. PyPI (Traditional Installation)
                3. Local Development (from source)
                4. Docker
              2. Tools
                1. Cursor Integration
              3. Configuration
                1. Server Settings
                2. Chart Settings
                3. Command Line Usage
              4. Docker
                1. Cursor MCP Integration
                  1. Quick Setup for Cursor
                  2. MERMAID-First Approach
                2. Available Tools
                  1. render_chart
                  2. configure_preferences
                3. Documentation
                  1. Additional Resources
                  2. Chart Examples
                4. 🔧 Configuration
                  1. Environment Variables
                  2. User Preferences
                5. 🚀 Advanced Usage
                  1. Custom Themes
                  2. High-Resolution Charts
                  3. Performance Optimization
                6. 🐛 Troubleshooting
                  1. Common Issues
                  2. Debug Mode
                7. 📝 Notes

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/MR901/mcp-plots'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server