DataClinic MCP
DataClinic MCP runs a full exploratory data analysis workflow over files and databases — inspect, diagnose, clean, and query data — returning ranked findings rather than raw data.
Load & inspect —
load_datasetreads CSV, TSV, Excel, Parquet, JSON/NDJSON, SQLite/PostgreSQL tables or guardedSELECTqueries into a session, returning shape, column classifications, missing-data summary, duplicates and top findings in one call (no follow-upprofileneeded).Profile columns —
profilegives full-population statistics per column with one recommended fix each, inbrief/standard/fulldetail; on database tables it pushes aggregates down into the database without moving rows.Find problems —
find_issuesranks every data-quality issue (missingness dependent on other columns, duplicate columns/rows, placeholder codes like-999, dates or nulls stored as text) filtered byhigh/medium/lowseverity.Deep-dive a column —
analyze_columnadapts to type: percentiles, histograms, normality and transform skew for numbers; value lists and encoding advice for categories; date breakdowns; key formats for identifiers.Explore relationships —
check_relationshipsranks the strongest pairs (Pearson, Spearman, Cramér's V, correlation ratio), finds near-duplicate columns, or ranks every column against atarget=orgroup_by=.Assess a target —
analyze_targetevaluates a prediction target (classification vs regression, class balance/skew, feature ranking, and leakage detection).Query data —
queryanswers precise questions in a safe, non-evalexpression language (price > 100 and country == "UK",mean(price, by=country)), or runs one read-onlySELECTin the database under timeout and row caps.Connect to databases —
connect_databaseopens read-only SQLite/PostgreSQL connections (credentials from env, never echoed) andexplore_schemabrowses schemas, tables, columns, keys and indexes.Clean data —
clean_dataapplies a batch of reversible operations (fill/flag/drop missing, dedupe, handle outliers, replace, merge variants, rename, cast, parse dates) as one undoable step, with unsafe operations skipped and explained.Manage session & history —
historylists or undoes changes;manage_sourceslists or closes open datasets/connections to free memory.Robust ingestion — detects encoding, delimiters, disguised nulls, text-stored numbers and mixed date formats, reporting every coercion explicitly; reads whole files, never a sample.
Not yet implemented: validate_rules, transform_data, reshape_data, plot, generate, export. (The supplied schema lists only load_dataset and manage_sources.)
Opens a read-only connection to a PostgreSQL database to browse schemas and tables, inspect columns, keys and indexes, and run profiling and query aggregates directly inside the database under a statement timeout and row cap — moving no rows unless explicitly loaded.
Opens a read-only connection to a SQLite database file to explore its schema and tables, inspect columns, keys and indexes, and execute profiling statistics and guarded read-only SELECT queries (or load a table into the session) for exploratory data analysis.
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., "@DataClinic MCP Load sales_data.csv and summarize the data quality issues"
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.
DataClinic MCP
An MCP server that lets an AI assistant run a full exploratory data analysis workflow — inspect a dataset, diagnose what is wrong with it, fix it, and write the result back out.
Status: early alpha. Phases 1–3 of 6 are complete and Phase 4 (cleaning) is under way. Twelve tools work today (
load_dataset,profile,find_issues,analyze_column,check_relationships,analyze_target,query,connect_database,explore_schema,clean_data,history,manage_sources), on files, SQLite and PostgreSQL. Transforms, reshaping, rule validation and output are not implemented yet. See Current state for exactly what runs.
Why another EDA server
Most data tools built for AI assistants return data. df.describe() on fifty
columns, a thirty-by-thirty correlation matrix, a hundred raw rows. The
assistant then has to work out what any of it means, and the numbers stay in
the conversation being re-sent on every later turn.
DataClinic returns findings:
10 columns, 5,150 rows. 4 column(s) need attention before analysis.
HIGH notes: 100% missing -> add a missingness flag rather than imputing (5,150 rows)
HIGH notes: entirely empty -> drop
MED country: 27% missing -> decide between imputation and a flag (1,412 rows)
MED age: 25% missing -> decide between imputation and a flag (1,277 rows)
MED 3% of rows are exact duplicates -> drop_duplicates unless repetition is meaningful
MED region_code: single value throughout -> drop; it carries no signalEvery response carries a token budget and stops when it reaches it, saying what it left out.
Statistics cover every row
Some tools profile a file by reading its first hundred rows. On a sorted file that produces answers that are simply wrong, without saying so. Measured on this project's own test fixture:
mean of | |
first 100 rows | 2.81 |
full population | 36.04 |
error | 92% |
DataClinic reads the whole file. A test asserts that a sorted and an unsorted copy of the same data profile identically.
Related MCP server: mcp-limsdq
Install
Requires Python 3.11+ and uv.
git clone https://github.com/Muhammad-hammad-farooque/DataClinic-mcp.git
cd DataClinic-mcp
uv syncOptional format support:
uv sync --extra excel # .xlsx, .xls
uv sync --extra parquet # .parquet
uv sync --extra sql # SQL guard and database access (Phase 3, in progress)Connect it
Claude Code
claude mcp add dataclinic -- uv --directory /path/to/DataClinic-mcp run dataclinic-mcpClaude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"dataclinic": {
"command": "uv",
"args": ["--directory", "/path/to/DataClinic-mcp", "run", "dataclinic-mcp"]
}
}
}Restart the client and the tools appear.
Current state
Working
Tool | What it does |
| Reads CSV, TSV, Excel, Parquet, JSON or NDJSON — or a database table ( |
| Full-population statistics per column with ranked findings, each carrying one recommended fix. Problem columns are shown in full and clean ones rolled up into a line; |
| Every data-quality problem, ranked, each with the one fix to apply. Beyond the per-column checks it finds missingness that depends on another column, identical columns, records repeated under fresh keys, placeholder codes such as |
| Deep dive on one column, adapted to its type. Numbers get percentiles, a histogram, a normality test and the skew left by each candidate transform, so the recommended fix names the simplest one that works. Categories get the full value list and encoding advice; dates a breakdown by year, month and weekday plus missing days; identifiers their key formats and repeated keys |
| Ranked relationships, never a full matrix. With no arguments: the strongest pairs of any type (Pearson and Spearman for numbers, bias-corrected Cramér's V for categories, the correlation ratio for mixed pairs) plus groups of near-interchangeable columns to prune. |
| Assesses a prediction target before modelling: classification or regression, class balance or skew, every feature ranked by strength, and leakage -- features that encode the answer, including categories that map one-to-one to classes (judged against chance, so an imbalanced target does not trigger false alarms) |
| Asks a loaded dataset a precise question in a small, safe expression language (Python syntax, never |
| Opens a read-only connection to a SQLite file or PostgreSQL database and reports dialect, version, schemas and table count. Credentials come from the environment, never echoed back |
| Browses a connection step by step: schemas, then tables with row estimates, then one table's columns, keys and indexes |
| Applies a batch of cleaning operations as one undoable step: fill, flag or drop missing values, drop duplicates/columns/rows ( |
| Lists a dataset's changes this session, or undoes the last |
| Lists what is open in the session, or closes one to free memory |
load_dataset returns a profile in its first response, so there is no need for
a follow-up call to describe what was just loaded.
On the way in, it handles:
encoding detection (UTF-8, UTF-8-BOM, cp1252, latin-1)
delimiter sniffing (
,;tab|)nulls disguised as
N/A,-,?,unknown,#N/Aand similarnumbers stored as text, including thousands separators (
"20,281.33")dates stored as text, including mixed formats
Every conversion is reported in a read.coerced field rather than done
silently.
Column classification: numeric, categorical, datetime, boolean, text, identifier, constant, empty. Identifiers are detected by a consecutive-run signature rather than uniqueness alone, so a column of unique prices is not mistaken for a key.
Not built yet
validate_rules · transform_data · reshape_data · plot · generate ·
export
· database connectivity
These are specified in speckit.md but not implemented. The
roadmap below gives the order.
Example
> Load tests/fixtures/messy.csv and tell me what is wrong with it{
"shape": [5150, 10],
"memory_mb": 1.72,
"columns": {
"numeric": ["age", "churn_score", "churned", "price", "revenue"],
"categorical": ["country"],
"datetime": ["signup_date"],
"text": ["customer_id"],
"constant": ["region_code"],
"empty": ["notes"]
},
"missing_cells_pct": 16,
"duplicate_rows": 150,
"read": {
"format": "csv",
"encoding": "utf-8",
"delimiter": ",",
"coerced": {
"revenue": "numeric (thousands separators removed)",
"signup_date": "datetime"
}
},
"summary": "10 columns, 5,150 rows. 4 column(s) need attention before analysis.",
"findings": ["..."]
}Design
Three ideas drive the implementation. The full reasoning is in
speckit.md.
Findings, not data. Each tool has a token budget (800 for load_dataset,
1,500 for a full profile). Findings are ranked by severity and emitted until the
budget is reached, then truncated reports what was omitted and how to get it.
Floats are rounded to three significant figures; absent fields are dropped
entirely.
Correct beats fast. Statistics are computed over the whole dataset. When
sampling eventually becomes necessary for large database tables, the response
will carry a sampled field stating the size and method — never silently.
Nothing is modified in place. Data is loaded into an in-memory session. The source file is never written to; a test asserts it is byte-identical after a full session. Cleaning operations, when they arrive, will mutate only the session and be reversible.
Errors are structured. Every failure returns a stable code, a message, the remedy to try next, and whether a retry could help:
{
"error": {
"code": "SOURCE_TOO_LARGE",
"class": "user",
"message": "orders has ~41,238,904 rows, above max_load_rows (5,000,000)",
"retryable": false,
"remedy": "use profile() for push-down analysis, or pass limit="
}
}Configuration
Environment variables, all optional:
Variable | Default | Purpose |
| 5,000,000 | Refuse to load more rows than this |
| 4,096 | Memory ceiling |
| working directory | Roots the server may read and write |
| 42 | Seed for any sampling, for reproducibility |
|
|
|
| EDA_MCP_STATEMENT_TIMEOUT | 30 | Seconds any database statement may run |
| EDA_MCP_DSN_<ALIAS> | — | Database URL for connect_database(alias=...) |
| DATABASE_URL | — | Fallback database URL |
Paths are resolved before checking, so ../ cannot escape an allowed root.
Databases. Put credentials in the server's environment, not the
conversation: EDA_MCP_DSN_WAREHOUSE=postgresql://user:pass@host/db makes
connect_database(alias="warehouse") work with no secret in the chat.
Connections are read-only in four independent layers: a read-only session,
a SQL guard that accepts only a single SELECT, bound parameters, and a
statement timeout with a row cap. SQLite files must sit under
EDA_MCP_ALLOWED_PATHS.
Logs are JSON on stderr — stdout carries the MCP protocol — and never
contain values from your data.
Roadmap
Phase | Scope | Status |
1 | Config, errors, logging, registry, loaders, budgeting, | done |
2 |
| done |
3 | Database read path — SQLite and PostgreSQL first, push-down profiling, SQL in | done |
4 |
| in progress ( |
5 |
| planned |
6 | Cost benchmark, performance gates, docs | planned |
Development
uv sync --group dev --extra sql --extra duckdb
uv run pytest # unit + adversarial suites
# integration tests against a real PostgreSQL (they skip without this variable)
EDA_TEST_POSTGRES_DSN=postgresql://user:pass@localhost/db uv run --extra postgres pytest -m integration
uv run pytest --cov=eda_mcp # coverage
uv run ruff check src tests # lint
uv run ruff format src tests # format
uv run mypy src/eda_mcp # strict type checkRegenerate the test fixtures — deliberately broken files covering mixed types, sorted data, disguised nulls, duplicates and cp1252 encoding:
uv run python tests/fixtures/make_fixtures.pyAll three gates must pass before a change lands: ruff, mypy --strict, and
the test suite.
Licence
Not yet licensed. The code is readable here, but until a licence is added it is "all rights reserved" and cannot be reused. A licence will be chosen before the first release.
Available Tools
2 toolsload_datasetARead-onlyIdempotent
Load a CSV, Excel, Parquet or JSON file into the session. Returns shape, column kinds, missing-data summary and the top findings -- do not call profile straight after this.
Inputs: source (required), alias, limit, options. Returns: object
manage_sourcesA
List the datasets and connections open in this session, or close one to free memory. action is 'list' or 'close'.
Inputs: alias, action. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one loads new data into the session, the other manages existing session sources. There is no overlap or ambiguity between them.
Both tool names use a verb_noun pattern (load_dataset, manage_sources), which is consistent. The slight deviation is that 'manage_sources' is broader than a single action, but the pattern is still predictable.
With only two tools, the server feels very thin for a data-clinic purpose. A data analysis server would typically need at least a few more operations (e.g., inspect, transform, summarize) to be useful, so the count is too low for the apparent scope.
The server covers loading data and managing sources, but lacks any analysis, transformation, or export operations. The domain is data handling, and the surface is severely incomplete for a 'DataClinic'—agents can load data but cannot do anything with it beyond listing/closing sources.
Maintenance
Related MCP Connectors
Clean messy tabular data and render publication-ready PNG charts from your AI assistant.
Company and industrial data for AI assistants: datasets, SQL, dashboards, alarms, with approvals.
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Bring professional data and tools to the AI you already use. QVeris helps AI assistants, products, and workflows find services, review supported scope, call them, and audit usage.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables LLM clients to load, clean, visualize, and analyze tabular datasets, and to generate multi-format analytic reports through natural language instructions.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to validate CSV exports against schemas, infer schemas from example files, profile datasets, and diff before/after exports for lab/LIMS data-quality checks.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to audit dbt project quality, profile warehouse data, detect schema drift, and auto-generate or update documentation and tests through natural language.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to audit dbt project quality, profile warehouse data, detect schema drift, and safely generate or update model documentation and tests through natural language.-