# 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](https://docs.astral.sh/uv/) (recommended) or pip
### Install with uv
```bash
cd mcp-tabular
uv sync
```
### Install with pip
```bash
cd mcp-tabular
pip install -e .
```
## Usage
### Running the Server Directly
```bash
# 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):
```json
{
"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](CONNECT_TO_CLAUDE_DESKTOP.md) for detailed instructions and troubleshooting.
See [TEST_PROMPTS.md](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:
```bash
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
```bash
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