What is Pandas Mcp Server

Pandas MCP Server is a server implementation that utilizes the Model Context Protocol (MCP) to handle CSV files, execute Pandas code, and generate interactive charts such as bar charts and pie charts.

Use cases

Use cases for pandas-mcp-server include loading and analyzing CSV datasets, executing complex data manipulations with Pandas, and creating interactive visual representations of data for presentations or dashboards.

How to use

To use pandas-mcp-server, ensure you have Python 3.11 or higher installed. Install the required packages using the command ‘pip install -r requirements.txt’. You can then utilize functions like read_metadata, run_pandas_code, bar_chart_to_html, and pie_chart_to_html to process CSV files and generate visualizations.

Key features

Key features of pandas-mcp-server include automatic detection of file encoding and delimiter, execution of user-provided Pandas code with security measures, and the ability to generate interactive HTML charts using Chart.js.

Where to use

Pandas MCP Server can be used in data analysis, data visualization, and reporting applications across various fields such as finance, marketing, and education.

Pandas MCP Server

This repository contains a server implementation using the Model Context Protocol (MCP) with functionalities to handle CSV files, execute Pandas code, and generate interactive charts (bar charts and pie charts).

Requirements

• Python 3.11 or higher
• Install required packages: pip install -r requirements.txt

Functions

read_metadata

• Description: Loads a CSV file and returns its column structure and sample data.
• Parameters:
  • file_path: Path to the CSV file.
• Returns:
  • A dictionary containing the columns and sample data from the CSV file.
• Notes:
  • Detects file encoding and delimiter automatically.
  • Limits file size to 100MB to prevent excessive memory usage.

run_pandas_code

• Description: Executes Pandas code provided as a string.
• Parameters:
  • code: String containing the Pandas code to execute.
• Returns:
  • A dictionary containing the result of the executed code and any variables created during execution.
• Security Notes:
  • Prevents execution of blacklisted operations such as os., sys., subprocess., open(, exec(, eval(, import os, import sys.
  • Provides detailed error messages and suggestions to help users resolve issues.

bar_chart_to_html

• Description: Generates an interactive HTML bar chart using Chart.js template.
• Parameters:
  • categories: List of category names for x-axis
  • values: List of numeric values for y-axis
  • title: Chart title (default: “Interactive Chart”)
• Returns:
  • A dictionary containing the file path and status information
• Example:

{
  "categories": [
    "Electronics",
    "Clothing",
    "Home Goods"
  ],
  "values": [
    120000,
    85000,
    95000
  ],
  "title": "Q1 Sales by Product Category"
}

pie_chart_to_html

• Description: Generates an interactive HTML pie chart using Chart.js template.
• Parameters:
  • labels: List of label names for each pie slice
  • values: List of numeric values for each slice
  • title: Chart title (default: “Interactive Pie Chart”)
• Returns:
  • A dictionary containing the file path and status information
• Example:

{
  "labels": [
    "Electronics",
    "Clothing",
    "Home Goods"
  ],
  "values": [
    120000,
    85000,
    95000
  ],
  "title": "Q1 Sales Distribution"
}

line_chart_to_html

• Description: Generates an interactive HTML line chart using Chart.js template.
• Parameters:
  • labels: List of label names for x-axis
    • datasets: List of datasets, each containing:
      • label: Name of the dataset
      • data: List of numeric values
  • title: Chart title (default: “Interactive Line Chart”)
• Returns:
  • A dictionary containing the file path and status information
• Example:

{
  "labels": [
    "Jan",
    "Feb",
    "Mar"
  ],
  "datasets": [
    {
      "label": "Sales",
      "data": [
        12000,
        15000,
        18000
      ]
    },
    {
      "label": "Expenses",
      "data": [
        8000,
        9000,
        10000
      ]
    }
  ],
  "title": "Monthly Performance"
}

Usage

1. Configure your MCP client with the following settings:

{
  "mcpServers": {
    "pandas": {
      "name": "pandas",
      "type": "stdio",
      "description": "run pandas code",
      "isActive": true,
      "command": "python",
      "args": [
        "${workspaceFolder}/server.py"
      ]
    }
  }
}

2. Use the configured MCP client to interact with the server and utilize the provided tools.

Workflow

1. Read metadata of your CSV file:

   • User prompt: “Read metadata of data/sample.csv and show me the column structure”
   • This will call read_metadata with the file path

2. Execute Pandas operations on the loaded data:

   • User prompt: “Group the data by category and calculate the sum for each group”
   • This will call run_pandas_code with the appropriate Pandas operation

3. Visualize the results using charts:

   • User prompt: “Create a bar chart showing sales by category”
   • This will call bar_chart_to_html with the grouped data
   • Example response:

{
  "status": "SUCCESS",
  "filepath": "/absolute/path/to/chart_1713443200.html"
}