data-quality-mcp
# data-quality-mcp
An MCP (Model Context Protocol) server that lets an AI client such as Claude inspect CSV datasets and report on their data quality.
It profiles columns, detects problems like disguised missing values, sentinels, duplicates and outliers, gives a 0–100 quality score, and suggests ordered cleaning steps. It is strictly read-only and confined to one directory.
## Architecture
```mermaid
flowchart LR
C["MCP client<br/>(Claude Desktop, Claude Code, Inspector)"] -- "JSON-RPC over stdio" --> S
subgraph S["data-quality-mcp"]
direction TB
SV["server.py<br/>FastMCP: tools, resource, prompt"]
SEC["security.py<br/>path validation, size limit, raw CSV read"]
P["profiling.py<br/>type inference, column profiles"]
I["issues.py<br/>detectors"]
SC["scoring.py<br/>0-100 score"]
CL["cleaning.py<br/>ordered suggestions"]
SV --> SEC
SV --> P & I & SC & CL
SC --> I
CL --> I
I --> P
end
SEC -- "read-only" --> D[("DATA_DIR/*.csv")]
```
`server.py` only registers things. All analysis lives in pure functions with no MCP imports (`profiling`, `issues`, `scoring`, `cleaning`), so they are easy to unit test. `security.py` is the only module that touches the filesystem.
## Tools
| Tool | Arguments | Returns |
|---|---|---|
| `list_datasets` | – | CSV files in `DATA_DIR` with size and row count (unsafe or oversized files are listed as unreadable) |
| `profile_dataset` | `name` | Rows, columns, and per column: inferred type, missing %, unique count, example values, numeric stats |
| `find_issues` | `name` | Issues with `type`, `severity` (high/medium/low), `column`, `message` and `details` |
| `quality_score` | `name` | 0–100 score, letter grade, breakdown (completeness, uniqueness, validity, consistency), one-line explanation |
| `preview_rows` | `name`, `n=5` | First `n` rows exactly as stored (capped at 20) |
| `suggest_cleaning` | `name` | Ordered cleaning steps with reasons and pandas code. Suggestions only, nothing is modified |
| Resource | Returns |
|---|---|
| `dataset://{name}/schema` | JSON with column names and inferred types |
| Prompt | Does |
|---|---|
| `audit_dataset(name)` | Asks the model to call `profile_dataset`, `find_issues` and `quality_score`, then write a short "Ready for ML training? yes/no + why" report |
All tools carry the MCP `readOnlyHint` annotation.
### What `find_issues` detects
| Issue type | Rule | Severity |
|---|---|---|
| `disguised_missing` | Placeholders such as `unknown`, `N/A`, `null`, `?`, `-`, or whitespace-only cells | medium if ≥ 5% of rows, else low |
| `sentinel_value` | `999`, `9999`, `-1`, `-999`… in a numeric column, **only when suspicious**: repeats ≥ 2×, and lies beyond Q1 − 3·IQR / Q3 + 3·IQR of the other values, or is negative while all other values are ≥ 0 | high |
| `high_missing` | > 30% of a column is blank or placeholder | high |
| `constant_column` | Only one distinct non-missing value | medium |
| `duplicate_rows` | Exact duplicate rows (count, %, example row indices) | high if > 5%, else medium |
| `outliers` | Tukey IQR rule (k = 1.5); returns count and bounds; sentinels are excluded first so they aren't double-counted | medium if ≥ 1%, else low |
| `numbers_stored_as_text` | ≥ 90% of values are numbers (incl. `1,200`, `$5`, `42 yrs`) but some are not plain numbers | medium |
### How `quality_score` works
```
score = 0.30·completeness + 0.20·uniqueness + 0.30·validity + 0.20·consistency
```
- **Completeness** is the average of the share of present cells and the share of rows with no missing cell.
- **Uniqueness** is the share of rows that are not exact duplicates.
- **Validity** is the average of the share of present cells matching their column's type (sentinels count as invalid) and the share of rows with no invalid cell.
- **Consistency** is the share of columns with no constant value, no IQR outliers and no numbers stored as text.
- **Auto-generated flag columns** (`age_was_missing`, `is_outlier`, `income_imputed`, `Unnamed: 0`…, which need both a flag-like name *and* binary values) are excluded everywhere. They are 100% complete by construction and would otherwise inflate completeness after cleaning.
## Setup
Requires Python 3.11+.
**With uv**
```bash
git clone <your-repo-url> data-quality-mcp && cd data-quality-mcp
uv venv && uv pip install -e ".[dev]"
uv run data-quality-mcp # starts the server on stdio (Ctrl+C to stop)
```
**With pip**
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
data-quality-mcp
```
The server reads CSVs from `DATA_DIR` (default `./data`, relative to the working directory). Sample data is included. To regenerate it:
```bash
python scripts/make_sample_data.py # writes data/customers_clean.csv and data/customers_messy.csv
```
**Run the checks**
```bash
ruff check . && ruff format --check .
pytest
```
## Try it with MCP Inspector
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser UI for calling a server's tools by hand (needs Node.js):
```bash
npx @modelcontextprotocol/inspector -e DATA_DIR="$PWD/data" .venv/bin/data-quality-mcp
```
Open the URL it prints, click **Connect**, then:
1. **Tools → list_datasets → Run** to see the two sample files.
2. **quality_score** with `name = customers_messy.csv` returns 85.0; `customers_clean.csv` returns 100.0.
3. **profile_dataset** with `name = ../pyproject.toml` returns a clear "Access denied" error.
4. **Resources** tab: `dataset://customers_messy.csv/schema`. **Prompts** tab: `audit_dataset`.
## Connect to Claude Desktop
Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`). Use **absolute paths**: Claude Desktop does not start in your project folder, so `./data` would not resolve to it.
```json
{
"mcpServers": {
"data-quality": {
"command": "/Users/you/projects/data-quality-mcp/.venv/bin/data-quality-mcp",
"env": {
"DATA_DIR": "/Users/you/projects/data-quality-mcp/data"
}
}
}
}
```
Fully quit and restart Claude Desktop. The six tools then appear in the chat's tools/connectors menu, and `audit_dataset` is listed among the server's prompts.
## Connect to Claude Code
```bash
claude mcp add data-quality \
--env DATA_DIR="$PWD/data" \
-- "$PWD/.venv/bin/data-quality-mcp"
```
Check it with `claude mcp list`, or `/mcp` inside a session. Add `--scope project` to share the config with your team through `.mcp.json`.
## Example conversation
> **You:** Is customers_messy.csv ready for training?
Claude calls the three tools (or you run the `audit_dataset` prompt). Abbreviated, these are what they actually returned:
**`profile_dataset`**: 525 rows, 13 columns. Notable columns:
| column | inferred type | missing % | unique |
|---|---|---|---|
| phone | text | 39.43 | 298 |
| email | text | 8.0 | 460 |
| city | categorical | 5.71 | 8 |
| age | integer | 3.05 | 75 |
| data_source | categorical | 0.0 | 1 |
**`find_issues`**: 10 issues, `{"high": 2, "medium": 6, "low": 2}`
```
high high_missing phone 39.43% missing (207 blank)
high sentinel_value days_since_last_purchase 999 appears 20 times, far outside the rest
medium duplicate_rows – 25 rows (4.76%) are exact duplicates
medium disguised_missing email 42 cells say 'unknown'
medium disguised_missing city 30 cells: 'N/A', '?', whitespace
medium numbers_stored_as_text age 18 values like '65 yrs'
medium constant_column data_source always 'legacy_crm'
medium outliers annual_income 8 values outside [18,903, 98,807]
low disguised_missing age 16 cells say 'unknown'
low disguised_missing plan 10 cells say '-'
```
**`quality_score`**: `85.0` (grade B). Completeness 72.6, uniqueness 95.2, validity 96.1, consistency 76.9.
> **Claude:**
> **Ready for ML training?** No. There are two high-severity issues and the score is 85/100.
> **Why:** `phone` is 39% empty; `days_since_last_purchase` uses 999 as a "never purchased" code in 20 rows, which would wreck any model of recency; 25 rows (4.8%) are duplicates; `age` mixes numbers with text like "65 yrs" and "unknown"; `annual_income` has 8 extreme values (from -5,000 up to 1.2M).
> **Score:** 85.0. The weakest dimension is completeness (72.6): only 261 of 525 rows have no missing value.
> **Fix first:** drop duplicates, turn placeholders and the 999 sentinel into NaN, and convert `age` to numeric. `suggest_cleaning` gives the code.
Running all 11 suggested steps on a copy raises the score from **85.0 to 96.6** with zero remaining issues. A test (`tests/test_sample_data.py`) checks this.
## Security
The server gives an AI model access to your filesystem, so it is locked down by default.
- **One allowed directory.** Only files inside `DATA_DIR` (default `./data`) can be read. Every tool, and the resource, goes through `security.resolve_dataset_path()`.
- **Path traversal blocked.** The requested name is joined to `DATA_DIR` and `resolve()`d, which collapses `..` and follows symlinks. The result must still be inside `DATA_DIR` (`Path.is_relative_to`). So `../../etc/passwd`, `sub/../../secret.csv` and similar names are rejected.
- **Symlinks can't escape.** Because the check runs on the *resolved* path, a `data/link.csv → /home/me/secret.csv` symlink is rejected. A symlink that stays inside `DATA_DIR` is allowed.
- **Absolute paths rejected** (`/etc/passwd`, `C:\...`, `\\server\share`) with a message explaining how to pass a relative name.
- **Only `.csv`.** The extension is checked on both the requested name and the real target, so `report.csv → notes.txt` is refused.
- **Size and output limits.** Files over **50 MB** are refused before being opened. `preview_rows` returns at most **20 rows** and reads only those rows.
- **Read-only.** No code path writes, renames or deletes files. `suggest_cleaning` returns text only. Tools are annotated `readOnlyHint: true`.
- **No crashes on bad input.** Validation failures, malformed CSVs, empty files and non-UTF-8 files raise `DatasetAccessError`, which the client receives as an MCP tool error (`isError: true`) with a readable message. The server keeps running; a test checks this.
- **No secrets.** The project needs no API keys or network access. `.gitignore` excludes `.env` and key files.
These checks are covered by `tests/test_security.py` (traversal, absolute paths, escaping symlinks, non-CSV files, missing files, a real 50 MB + 1 byte file) and `tests/test_mcp_server.py` (the same errors through the MCP client).
## Design decisions
- **Read every cell as a raw string** (`dtype=str, keep_default_na=False`). Pandas would otherwise silently turn `"N/A"` into NaN and `"007"` into 7, hiding exactly the problems this tool looks for. Types are inferred afterwards.
- **Type inference with a 90% threshold.** A column is numeric if ≥ 90% of its non-missing values are plain numbers. That way a numeric column polluted with `"65 yrs"` is still recognized as numeric, and then flagged as *numbers stored as text*, instead of being misclassified as text.
- **Sentinels must look suspicious.** Flagging every 999 would produce false positives (a $999 price is normal), so a sentinel has to repeat and sit beyond 3×IQR, or be negative in an otherwise non-negative column.
- **Each problem is reported once.** Sentinels are removed before outlier detection, and placeholders are handled by the disguised-missing detector rather than counted as "text in a numeric column".
- **Cell- *and* row-level rates in the score.** With cell rates only, a column that is 40% empty is about 3% of a 13-column table, and the messy sample scored an "A" (92.9). Averaging in the row rate (rows that survive `dropna()`) reflects what a model actually sees; messy now scores 85.0 against 100.0 for clean.
- **Flag columns excluded from scoring.** The cleaning plan suggests adding `phone_was_missing` indicators. Without the exclusion, adding them would inflate completeness. Detection requires a flag-like name *and* binary values, so a real feature like `is_active` is not excluded.
- **Cleaning order matters.** Dedupe → placeholders to NaN → numeric conversion → sentinels → drop constant/sparse columns → outliers → re-verify. A test executes the generated pandas code and checks the score goes up.
- **`server.py` only does registration.** `build_server(data_dir)` is a factory, so tests point the server at fixture directories without touching environment variables.
- **MCP SDK 1.x (`mcp>=1.10,<2`).** The brief asked for FastMCP, which lives at `mcp.server.fastmcp` in SDK 1.x. In SDK 2.x it was renamed `MCPServer` and other APIs changed, so the dependency is pinned below 2.
## Limitations
- CSV only, UTF-8 only, comma-delimited (pandas defaults); no Excel or Parquet, and no delimiter sniffing.
- The whole file (≤ 50 MB) is loaded into memory for analysis; there is no streaming or sampling.
- Only files directly inside `DATA_DIR` are listed; subdirectories are not scanned.
- Dataset names containing `:` are rejected (this blocks Windows drive paths such as `C:x.csv`), so a file literally named `a:b.csv` cannot be read.
- Heuristics are heuristics. The placeholder list is English-centric, type inference is threshold-based, and IQR assumes roughly unimodal data (skewed columns such as incomes can produce "outliers" that are real).
- Only exact duplicates are found; near-duplicates (`"Alex Smith"` vs `"alex smith "`) are not.
- No cross-column rules (e.g. `signup_date` after `last_purchase`), no PII detection, and no tracking of quality over time.
- The score weights are fixed and opinionated; they are not configurable per use case.
## What I'd build next
- **Configurable rules:** per-dataset YAML for expected types, allowed ranges, custom placeholder tokens and score weights.
- **Near-duplicate detection** (normalized strings, fuzzy matching on key columns) and **cross-column checks**.
- **PII detection** (emails, phones, IDs) with a warning before data is used for training.
- **Label and leakage checks** for ML: class imbalance, target leakage, train/test drift between two files.
- **Parquet / Excel support** and chunked reading for files over 50 MB.
- **An opt-in `apply_cleaning` tool** that writes a *new* file to a separate output directory, never overwriting the source, to keep the read-only guarantee for inputs.
- **Quality history:** store scores over time and alert when a dataset's quality drops.
## Project layout
```
src/data_quality_mcp/
server.py FastMCP app: tool/resource/prompt registration only
security.py path validation, size limit, raw CSV loading
profiling.py type inference, column profiles, schema
issues.py the seven detectors + find_issues
scoring.py 0-100 score and breakdown
cleaning.py ordered cleaning suggestions
scripts/make_sample_data.py seeded synthetic data generator
data/ customers_clean.csv, customers_messy.csv (synthetic)
tests/ unit, security, sample-data and in-process MCP tests
```
## License
MIT. See [LICENSE](LICENSE). The sample data is synthetic: names come from short generic lists and all emails use the reserved `example.com` domain.
TDQS
Scored across 6 tools
Each tool targets a distinct output: file listing, structural profiling, issue detection, a single score, raw row preview, and cleaning recommendations. profile_dataset vs find_issues vs quality_score are related but clearly differentiated by what they return (stats vs issue list vs 0-100 score). No overlaps that would cause misselection.
Five tools follow a clean verb_noun pattern (profile_dataset, find_issues, preview_rows, suggest_cleaning, list_datasets). quality_score breaks the pattern with a noun_noun construction, a minor but visible deviation.
Six tools is well-scoped for a data quality analysis server, and each covers a distinct stage of the workflow. Nothing feels redundant or padded.
The read-only analysis lifecycle is well covered: discover, profile, detect issues, score, preview, and recommend fixes. The one gap is a way to apply or export the cleaning suggestions, so the workflow ends at recommendations rather than a fixable dataset.