MCP Tabular Data Analysis Server

A Model Context Protocol (MCP) server that provides tools for analyzing numeric and tabular data. Works with CSV files and SQLite databases.

Demo

auto_insights

<img width="656" height="815" alt="image" src="https://github.com/user-attachments/assets/5555e251-55b8-464e-9c92-91f9059a5d0f" />

data_quality_report

<img width="854" height="856" alt="image" src="https://github.com/user-attachments/assets/bb7fcc7f-35a6-4fb2-8b35-5eafd6ce782b" />

analyze_time_series

<img width="600" height="873" alt="image" src="https://github.com/user-attachments/assets/3e5a3c75-0f8d-4f6e-b745-a1e4b33cf809" />

Features

Core Tools

Tool	Description
list_data_files	List available CSV and SQLite files in the data directory
describe_dataset	Generate statistics for a dataset (shape, types, distributions, missing values)
detect_anomalies	Find outliers using Z-score or IQR methods
compute_correlation	Calculate correlation matrices between numeric columns
filter_rows	Filter data using various operators (eq, gt, lt, contains, etc.)
group_aggregate	Group data and compute aggregations (sum, mean, count, etc.)
query_sqlite	Execute SQL queries on SQLite databases
list_tables	List all tables and schemas in a SQLite database

Analytics Tools

Tool	Description
create_pivot_table	Create Excel-style pivot tables with flexible aggregations
data_quality_report	Data quality assessment with scores and recommendations
analyze_time_series	Time series analysis with trends, seasonality, and moving averages
generate_chart	Create visualizations (bar, line, scatter, histogram, pie, box plots)
merge_datasets	Join/merge two datasets together (inner, left, right, outer joins)
statistical_test	Hypothesis testing (t-test, ANOVA, chi-squared, correlation tests)
auto_insights	Discover patterns and insights
export_data	Export filtered/transformed data to new CSV files

Installation

Prerequisites

• Python 3.10+
• uv (recommended) or pip

Install with uv

cd mcp-tabular
uv sync

Install with pip

cd mcp-tabular
pip install -e .

Usage

Running the Server Directly

# With uv
uv run mcp-tabular

# With pip installation
mcp-tabular

Configure with Claude Desktop

1. Locate your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this configuration (replace /Users/kirondeb/mcp-tabular with your actual path):

{
  "mcpServers": {
    "tabular-data": {
      "command": "/Users/kirondeb/mcp-tabular/.venv/bin/python",
      "args": [
        "-m",
        "mcp_tabular.server"
      ]
    }
  }
}

3. Restart Claude Desktop (quit and reopen)

4. Test by asking Claude: "Describe the dataset in data/sample_sales.csv"

See CONNECT_TO_CLAUDE_DESKTOP.md for detailed instructions and troubleshooting.

See TEST_PROMPTS.md for example prompts.

Sample Data

The project includes sample data for testing:

• data/sample_sales.csv - Sales transaction data
• data/sample.db - SQLite database with customers, orders, and products tables

To create the SQLite sample database:

python scripts/create_sample_db.py

Path Resolution

All file paths are resolved relative to the project root directory:

• Relative paths like data/sample_sales.csv work from any working directory
• Absolute paths also work as expected
• Paths resolve relative to where mcp_tabular is installed

Tool Examples

List Data Files

List available data files:

list_data_files()

Lists all CSV and SQLite files in the data directory with metadata.

Describe Dataset

Generate statistics for a dataset:

describe_dataset(file_path="data/sample_sales.csv")

Includes shape, column types, numeric statistics (mean, std, median, skew, kurtosis), categorical value counts, and a sample preview.

Detect Anomalies

Find outliers in numeric columns:

detect_anomalies(
    file_path="data/sample_sales.csv",
    column="total_sales",
    method="zscore",
    threshold=3.0
)

Supports zscore and iqr methods.

Compute Correlation

Calculate correlations between numeric columns:

compute_correlation(
    file_path="data/sample_sales.csv",
    method="pearson"
)

Includes full correlation matrix and top correlations ranked by strength.

Filter Rows

Filter data based on conditions:

filter_rows(
    file_path="data/sample_sales.csv",
    column="category",
    operator="eq",
    value="Electronics"
)

Operators: eq, ne, gt, gte, lt, lte, contains, startswith, endswith

Group & Aggregate

Group data and compute aggregations:

group_aggregate(
    file_path="data/sample_sales.csv",
    group_by=["category", "region"],
    aggregations={"total_sales": ["sum", "mean"], "quantity": ["count"]}
)

Query SQLite

Execute SQL queries on databases:

query_sqlite(
    db_path="data/sample.db",
    query="SELECT * FROM customers WHERE lifetime_value > 1000"
)

List Tables

List tables and schemas in a SQLite database:

list_tables(db_path="data/sample.db")

Advanced Analytics Examples

Create Pivot Table

Create Excel-style pivot tables:

create_pivot_table(
    file_path="data/sample_sales.csv",
    index=["region"],
    columns=["category"],
    values="total_sales",
    aggfunc="sum"
)

Data Quality Report

Generate a data quality assessment:

data_quality_report(file_path="data/sample_sales.csv")

Includes completeness score, duplicate detection, outlier analysis, and an overall quality grade (A-F).

Time Series Analysis

Analyze trends and seasonality:

analyze_time_series(
    file_path="data/sample_sales.csv",
    date_column="order_date",
    value_column="total_sales",
    freq="M",
    include_forecast=True
)

Generate Charts

Create visualizations (returned as base64 images):

generate_chart(
    file_path="data/sample_sales.csv",
    chart_type="bar",
    x_column="category",
    y_column="total_sales",
    title="Sales by Category"
)

Supported chart types: bar, line, scatter, histogram, pie, box

Merge Datasets

Join or merge two datasets:

merge_datasets(
    file_path_left="data/orders.csv",
    file_path_right="data/customers.csv",
    on=["customer_id"],
    how="left"
)

Statistical Testing

Run hypothesis tests:

statistical_test(
    file_path="data/sample_sales.csv",
    test_type="ttest_ind",
    column1="total_sales",
    group_column="region",
    alpha=0.05
)

Supported tests: ttest_ind, ttest_paired, chi_squared, anova, mann_whitney, pearson, spearman

Auto Insights

Discover patterns and insights:

auto_insights(file_path="data/sample_sales.csv")

Includes insights about correlations, outliers, skewed distributions, missing data, and more.

Export Data

Export filtered data to a new CSV:

export_data(
    file_path="data/sample_sales.csv",
    output_name="electronics_sales",
    filter_column="category",
    filter_operator="eq",
    filter_value="Electronics",
    sort_by="total_sales",
    sort_ascending=False
)

Development

Run Tests

uv run pytest

Project Structure

mcp-tabular/
├── src/
│   └── mcp_tabular/
│       ├── __init__.py
│       └── server.py      # Main MCP server implementation
├── data/
│   ├── sample_sales.csv   # Sample CSV data
│   └── sample.db          # Sample SQLite database
├── scripts/
│   └── create_sample_db.py
├── pyproject.toml
├── claude_desktop_config.json
└── README.md

License

MIT