MCPmed/seabornMCP

Seaborn MCP

⚠️ Development Warning ⚠️

This project is currently in active development and is not yet production-ready.

• The MCP stdio server is functional but may have bugs or incomplete features
• API endpoints and functionality may change without notice
• Use at your own risk and report any issues you encounter

We recommend testing thoroughly in a development environment before using in production.

An MCP (Model Context Protocol) server that provides beautiful, out-of-the-box plotting capabilities using Seaborn. This allows AI assistants like Claude to create stunning visualizations without writing repetitive boilerplate code.

Features

• Jupyter Notebook Integration: Manages Jupyter kernels for interactive code execution
• Beautiful Plots Out-of-the-Box: Pre-configured Seaborn plots with sensible defaults
• Multiple Plot Types: Scatter, line, bar, heatmap, distribution, box, pair, and regression plots
• Automatic File Saving: Plots are automatically saved to the seaborn_outputs directory
• Session Management: Create and manage multiple notebook sessions
• Style Configuration: Easy theming and style customization

Installation

pip install seaborn-mcp

Or install from source:

git clone https://github.com/yourusername/seaborn-mcp.git
cd seaborn-mcp
pip install -e .

Quick Start

Starting the Server

# Start the MCP server
seaborn-mcp serve

# List available tools
seaborn-mcp list-tools

# Show server info
seaborn-mcp info

Using with Claude Desktop

Add the following to your Claude Desktop configuration:

{
  "mcp-servers": {
    "seaborn": {
      "command": "seaborn-mcp",
      "args": ["serve"]
    }
  }
}

Available Tools

Notebook Management

• create_notebook - Create a new Jupyter notebook session
• execute_code - Execute Python code in the active notebook
• list_notebooks - List all notebook sessions
• switch_notebook - Switch between notebook sessions
• shutdown_notebook - Close a notebook session

Plotting Tools

• create_scatter_plot - Create scatter plots with optional grouping
• create_line_plot - Create line plots with trends
• create_bar_plot - Create bar charts (vertical or horizontal)
• create_heatmap - Create correlation matrices and heatmaps
• create_distribution_plot - Create histograms, KDE, or ECDF plots
• create_box_plot - Create box plots for distributions
• create_pair_plot - Create matrix of plots for multiple variables
• create_regression_plot - Create regression plots with fitted lines
• set_plot_style - Configure default plotting style and theme

Example Usage

Here's how an AI assistant would use these tools:

# 1. Create a notebook session
create_notebook(nbid="analysis1")

# 2. Create sample data
execute_code("""
import pandas as pd
import numpy as np

# Create sample dataset
np.random.seed(42)
data = pd.DataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100),
    'category': np.random.choice(['A', 'B', 'C'], 100),
    'size': np.random.uniform(10, 100, 100)
})
""")

# 3. Create a scatter plot
create_scatter_plot(
    data_code="# Data already loaded",
    x="x",
    y="y",
    hue="category",
    size="size",
    title="Sample Scatter Plot",
    save_name="my_scatter"
)

# 4. Create a distribution plot
create_distribution_plot(
    data_code="# Data already loaded",
    column="x",
    kind="hist",
    hue="category",
    title="Distribution of X by Category",
    save_name="distribution_x"
)

Architecture

The package follows a modular architecture inspired by the scanpy-mcp implementation:

seaborn_mcp/
├── backend/           # Jupyter kernel management and execution
│   ├── executor.py    # JupyterPlotExecutor class
│   └── server.py      # MCP tool definitions
├── server/            # Main MCP server
│   └── __init__.py    # SeabornMCPManager
├── shared/            # Shared utilities
│   └── mcp_base.py    # Base MCP manager class
└── cli.py             # Command-line interface

Key Components

1. JupyterPlotExecutor: Manages Jupyter kernels and executes code
2. NotebookManager: Handles multiple notebook sessions
3. MCP Tools: FastMCP-based tool definitions for plotting
4. SeabornMCPManager: Main server manager
5. CLI: Command-line interface for server management

Development

Setting up for Development

# Clone the repository
git clone https://github.com/yourusername/seaborn-mcp.git
cd seaborn-mcp

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Quality

# Format code
black seaborn_mcp/

# Lint code
ruff check seaborn_mcp/

# Type checking
mypy seaborn_mcp/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

This implementation is based on the architecture pattern from the scanpy-mcp project, adapted for Seaborn plotting capabilities.# seabornMCP