data-quality-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@data-quality-mcp audit customers_messy.csv for issues and suggest cleaning steps"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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.
Related MCP server: Dataset Explorer MCP Server
Tools
Tool | Arguments | Returns |
| – | CSV files in |
|
| Rows, columns, and per column: inferred type, missing %, unique count, example values, numeric stats |
|
| Issues with |
|
| 0–100 score, letter grade, breakdown (completeness, uniqueness, validity, consistency), one-line explanation |
|
| First |
|
| Ordered cleaning steps with reasons and pandas code. Suggestions only, nothing is modified |
Resource | Returns |
| JSON with column names and inferred types |
Prompt | Does |
| Asks the model to call |
All tools carry the MCP readOnlyHint annotation.
What find_issues detects
Issue type | Rule | Severity |
| Placeholders such as | medium if ≥ 5% of rows, else low |
|
| high |
| > 30% of a column is blank or placeholder | high |
| Only one distinct non-missing value | medium |
| Exact duplicate rows (count, %, example row indices) | high if > 5%, else medium |
| 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 |
| ≥ 90% of values are numbers (incl. | medium |
How quality_score works
score = 0.30·completeness + 0.20·uniqueness + 0.30·validity + 0.20·consistencyCompleteness 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
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
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
data-quality-mcpThe server reads CSVs from DATA_DIR (default ./data, relative to the working directory). Sample data is included. To regenerate it:
python scripts/make_sample_data.py # writes data/customers_clean.csv and data/customers_messy.csvRun the checks
ruff check . && ruff format --check .
pytestTry it with MCP Inspector
MCP Inspector is a browser UI for calling a server's tools by hand (needs Node.js):
npx @modelcontextprotocol/inspector -e DATA_DIR="$PWD/data" .venv/bin/data-quality-mcpOpen the URL it prints, click Connect, then:
Tools → list_datasets → Run to see the two sample files.
quality_score with
name = customers_messy.csvreturns 85.0;customers_clean.csvreturns 100.0.profile_dataset with
name = ../pyproject.tomlreturns a clear "Access denied" error.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.
{
"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
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 |
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:
phoneis 39% empty;days_since_last_purchaseuses 999 as a "never purchased" code in 20 rows, which would wreck any model of recency; 25 rows (4.8%) are duplicates;agemixes numbers with text like "65 yrs" and "unknown";annual_incomehas 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 convertageto numeric.suggest_cleaninggives 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 throughsecurity.resolve_dataset_path().Path traversal blocked. The requested name is joined to
DATA_DIRandresolve()d, which collapses..and follows symlinks. The result must still be insideDATA_DIR(Path.is_relative_to). So../../etc/passwd,sub/../../secret.csvand similar names are rejected.Symlinks can't escape. Because the check runs on the resolved path, a
data/link.csv → /home/me/secret.csvsymlink is rejected. A symlink that stays insideDATA_DIRis 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, soreport.csv → notes.txtis refused.Size and output limits. Files over 50 MB are refused before being opened.
preview_rowsreturns at most 20 rows and reads only those rows.Read-only. No code path writes, renames or deletes files.
suggest_cleaningreturns text only. Tools are annotatedreadOnlyHint: 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.
.gitignoreexcludes.envand 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_missingindicators. Without the exclusion, adding them would inflate completeness. Detection requires a flag-like name and binary values, so a real feature likeis_activeis 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.pyonly 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 atmcp.server.fastmcpin SDK 1.x. In SDK 2.x it was renamedMCPServerand 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_DIRare listed; subdirectories are not scanned.Dataset names containing
:are rejected (this blocks Windows drive paths such asC:x.csv), so a file literally nameda:b.csvcannot 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_dateafterlast_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_cleaningtool 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 testsLicense
MIT. See LICENSE. The sample data is synthetic: names come from short generic lists and all emails use the reserved example.com domain.
Available Tools
6 toolsfind_issuesBRead-only
Find data quality issues (with severity and column): disguised missing values, sentinels like 999, >30% missing columns, constant columns, duplicate rows, IQR outliers and numbers stored as text.
Inputs: name (required). Returns: object
list_datasetsARead-only
List the CSV files in the data directory with their size and row count.
Inputs: no named parameters. Returns: object
preview_rowsBRead-only
Return the first n rows of a dataset exactly as stored (n is capped at 20).
Inputs: name (required), n. Returns: object
profile_datasetBRead-only
Profile a dataset: rows, columns, and per column the inferred type, missing %, unique count and example values.
Inputs: name (required). Returns: object
quality_scoreBRead-only
Score a dataset 0-100 with a breakdown (completeness, uniqueness, validity, consistency) and a one-line explanation of how the score is computed.
Inputs: name (required). Returns: object
suggest_cleaningBRead-only
Suggest concrete, ordered cleaning steps (with pandas code) based on find_issues. Suggestions only: no file is changed.
Inputs: name (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Related MCP Connectors
Profile, clean and validate CSV/Excel data: schemas, dates, numbers, duplicates. Never guesses.
Ask questions about a CSV in plain English and get answers, charts and cleaned data back.
Auto-discover validation rules from data — scan, profile, health-score. No rules to write.
Validate and clean CSV before import. Find duplicates, missing values and invalid dates with row-level reports. Apply only the cleanup you request; files are not retained. Run view_csv_demo free without a key. Custom CSV: EUR 9 for 100 operations, valid 90 days, no subscription. Setup: https://check.orvel.dev/docs/
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides tools to inspect dataset schema, profile, preview, and execute read-only SQL queries on uploaded CSV/Excel files.-
- AlicenseBqualityBmaintenanceEnables AI clients to explore and analyze CSV datasets via tools for dataset overview, statistical summaries, missing value analysis, duplicate detection, correlation analysis, and outlier detection.942 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI clients to perform data analysis on CSV datasets through tools for dataset info, summaries, missing value detection, regional sales filtering, and column statistics.-
- FlicenseNot gradedqualityCmaintenanceEnables AI-assisted CSV data quality profiling through MCP tools, offering analysis reports and quality scores while preserving privacy by processing only aggregated data.-