Skip to main content
Glama

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

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

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-mcp

The 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.csv

Run the checks

ruff check . && ruff format --check .
pytest

Try 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-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.

{
  "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

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. The sample data is synthetic: names come from short generic lists and all emails use the reserved example.com domain.

Available Tools

6 tools
find_issuesB
Read-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_datasetsA
Read-only

List the CSV files in the data directory with their size and row count.

Inputs: no named parameters. Returns: object

preview_rowsB
Read-only

Return the first n rows of a dataset exactly as stored (n is capped at 20).

Inputs: name (required), n. Returns: object

profile_datasetB
Read-only

Profile a dataset: rows, columns, and per column the inferred type, missing %, unique count and example values.

Inputs: name (required). Returns: object

quality_scoreB
Read-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_cleaningB
Read-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

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      9
      42 PyPI
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to perform data analysis on CSV datasets through tools for dataset info, summaries, missing value detection, regional sales filtering, and column statistics.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI-assisted CSV data quality profiling through MCP tools, offering analysis reports and quality scores while preserving privacy by processing only aggregated data.
      -