Dataframe Analyst

You have a FastMCP-based server that enables exploratory data analysis on CSV, Excel, Google Sheets, and Google Drive sources, and can export reports in Markdown, JSON, or HTML to local storage or Google Drive. It auto-generates input schemas from type hints and supports a CLI fallback for quick debugging and direct use.

How to use

To use this server with an MCP client, start the server in STDIO mode and connect a local client session. The server exposes a set of data analysis tools that you can invoke from the client to load data, infer schemas, compute profiles, find correlations, detect outliers, group data, and export reports.

How to use

Start the MCP server in STDIO mode from your terminal. This runs a Python process that your MCP client can communicate with over standard input and output.

How to use

python -m dataframe_analyst_mcp.server --mcp

What you can do with the MCP server

Once connected, you can perform a sequence of actions to analyze your data and generate reports. The key tools include loading data, inferring schema, computing descriptive profiles, examining correlations, detecting outliers, performing group-by aggregations, and exporting reports to a chosen destination.

How to use

Quick actions you can perform after connecting include: loading data from local paths or Google sources, generating a data schema, producing descriptive statistics with configurable percentiles, computing a correlation matrix, identifying outliers, grouping by keys with configurable metrics, and exporting a formatted report.

How to use

For guidance on how to trigger each action from your MCP client, refer to the tool names and their typical parameters described in your client’s documentation. The server’s capabilities map directly to these tool calls: load_data, infer_schema, missing_report, profile, correlation, detect_outliers, groupby, and export_report.

How to install

Prerequisites: ensure you have Python 3.10 or newer installed on your system, and that you can access a terminal or command prompt.

How to install

Set up a Python virtual environment and install the package in editable mode to develop and run locally.

How to install

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -U pip setuptools wheel

# Install the package in editable mode
python -m pip install -e .

# Install base dependencies (if not installed automatically)
python -m pip install mcp pandas openpyxl "xlrd==1.2.0"

# Optional extras for Google Drive/Sheets
python -m pip install "gspread>=6" "google-auth>=2.28" "google-auth-oauthlib>=1.2" "pydrive2>=1.19"

How to install

Note: xlrd==1.2.0 is required only for old .xls files. For .xlsx, openpyxl is used.

Configuration and credentials

Google credentials are optional. If you plan to access Google Drive or Sheets, you can use a Service Account or OAuth Desktop flow as described in the guidance section.

Configuration and credentials

Service Account (SA) setup steps include creating a Service Account, enabling Drive and Sheets APIs, downloading the JSON key to secrets/sa.json, and exporting the path through GOOGLE_APPLICATION_CREDENTIALS. Share Sheets or Drive folders with the SA email to grant access.

Configuration and credentials

OAuth Desktop setup involves configuring an external consent screen, creating a Desktop client, and saving client_secret.json. You can optionally export paths for token and client secrets to environment variables when running the server.

Usage as MCP server (stdio)

Run the server in MCP mode to accept commands from a client. The standard command to start the server is the following.

Usage as MCP server (stdio)

python -m dataframe_analyst_mcp.server --mcp

Configuration example for MCP client

If you want to integrate this server with a client, you can reference the following configuration pattern for an MCP connection. The server is started with the Python module and the --mcp flag to enable MCP protocol handling.

Troubleshooting and notes

If you encounter module import issues, ensure you install in editable mode from the project root and that the source contains the expected package path. If the client cannot connect over STDIO, set PYTHONPATH to include the source directory.

Troubleshooting and notes

Drive/Sheets 403/404 errors usually indicate missing or misconfigured permissions. Share resources with the Service Account or complete the OAuth Desktop flow as described above.

Tools and capabilities

The server exposes the following data analysis tools to the MCP client: load_data, infer_schema, missing_report, profile, correlation, detect_outliers, groupby, and export_report. Each tool performs a specific analytic or export function described in its dedicated implementation.

Notes on export destinations

Exported reports can be saved locally or pushed to Google Drive folders, depending on the destination configuration provided by your MCP client.

Additional notes

You can test a workflow by loading a local CSV, generating the schema, profiling key numeric columns, computing correlations, identifying outliers, grouping by a categorical key, and exporting a formatted report to your chosen destination.

Available tools

load_data

Load a dataset from a local path or Google source and create a session view for subsequent operations.

infer_schema

Infer per-column data types and provide basic metadata about the dataset.

missing_report

Compute missing value percentages and counts per column to understand data quality.

profile

Produce descriptive statistics with configurable percentiles for numeric columns.

correlation

Compute a correlation matrix using methods such as pearson, spearman, or kendall.

detect_outliers

Identify outliers using IQR or Z-score methods.

groupby

Aggregate data by one or more keys with configurable metrics per column.

export_report

Export a formatted report (md/json/html) to a local path or Google Drive folder.