Skip to main content
Glama
Sign In
tabular-ds-mcp

tabular-ds-mcp

by YusufErem
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

tabular-ds-mcp

tests Python 3.10–3.13 License: MIT Open In Colab

Honest first-hour checks for tabular ML, as tools your AI coding agent can call.

An MCP server for Claude Code, Cursor and Claude Desktop, and a plain Python library. It inspects a competition folder, profiles the data, compares train and test, gives a cross-validated baseline with the competition's metric next to a no-skill baseline, and tells you when random K-fold would overstate your score.

Demo: python -m tabular_ds_mcp.demo

Real output of python -m tabular_ds_mcp.demo on synthetic data, rendered by docs/make_media.py.

Try it in one minute

pip install git+https://github.com/YusufErem/tabular-ds-mcp.git      # Python ≥ 3.10
python -m tabular_ds_mcp.demo

The demo writes synthetic data to ./tabular_ds_mcp_demo, runs every tool in order and prints the report above (about 20 seconds). No account, API key or download is needed. To try it in the browser instead, open the Colab notebook.

Related MCP server: MCP Software-Engineering RL Environment

Why

Random K-fold vs time-ordered and group folds

Random K-fold assumes every row is independent. When the test rows come later in time, or belong to customers the model has never seen, it quietly overstates the score. With time_col or group_col, cv_baseline validates the way the test set was built, runs the same model on random splits of the same rows, and reports the gap. Both panels come from the demo; on independent rows the two agree and no warning is raised.

Three rules are built in: every score is returned next to a no-skill baseline, nothing is fitted on rows it is scored on, and the validation scheme follows the data.

Use it from an AI agent

git clone https://github.com/YusufErem/tabular-ds-mcp.git && cd tabular-ds-mcp
python3 -m venv .venv && .venv/bin/pip install -e .

Claude Code

claude mcp add tabular-ds -- "$(pwd)/.venv/bin/tabular-ds-mcp"
cp -r skills/tabular-playbook ~/.claude/skills/              # optional: the agent workflow below

Cursor (.cursor/mcp.json) or Claude Desktop (claude_desktop_config.json)

{ "mcpServers": { "tabular-ds": { "command": "/absolute/path/to/tabular-ds-mcp/.venv/bin/tabular-ds-mcp" } } }

Then ask, for example: “Inspect data/, run the checks it suggests and give me a baseline with the competition metric.”

skills/tabular-playbook/SKILL.md tells the agent the order of the checks (inspect → profile → compare → baseline → explain → submission), what the thresholds mean (adversarial AUC 0.55 / 0.65, PSI 0.1 / 0.25), when to switch to time or group folds, and how to report: every number next to its baseline, every warning reported, no number that did not come from a tool.

Tools

Tool

What it returns

inspect_competition

Start here. Finds train / test / sample submission in a folder, the target and ID columns, the task, the submission format and a likely metric, whether test rows lie later in time or belong to unseen groups, extra tables that need a join, image or text content, and the exact calls to make next

profile_dataset

Shape, column types, missing values, cardinality, duplicate rows, target balance, and warnings: constant or ID-like columns, high missing rates, possible leakage, date columns, repeated keys, free text, file paths

compare_train_test

Column and dtype mismatches, unseen categories, PSI and KS per feature, an adversarial-validation AUC with a verdict, where the test rows sit in time, and how many test rows belong to keys never seen in train

cv_baseline

Gradient-boosting scores with the competition metric, fold spread and the no-skill baseline on the same folds. Random, time-ordered or group folds; with time or group folds it also reports how much random validation would overstate the score

explain_model

Permutation importance on a hold-out split (random, latest 20% in time, or unseen groups), plus features that add nothing

fit_predict

Fits on all rows and writes the submission in the sample's format: probability, value, label, top-k labels or one probability column per class

check_submission

Columns, row count, duplicated / missing IDs, missing values, constant predictions, [0, 1] range, per-row probability sums, labels per row for top-k submissions

All tools read CSV or Parquet, detect binary / multiclass / regression targets, and sample large files for speed.

What it adapts to

Situation

How it is detected

What changes

Test rows come later in time

date or time-index columns whose test range lies after the training range

time_col: folds train on the past and score the next time block; the hold-out for importance is the latest 20%; adversarial validation is also reported without the time column

Repeated keys (customer, store, card) with new keys in test

key-like column names, repeated values, share of test rows with an unseen key

group_col: no key sits in both parts of a fold, and the key is left out of the features

Competition metric

given by you (metric=), hinted by the sample submission

roc_auc, pr_auc, log_loss, accuracy, f1, mcc, macro_f1, roc_auc_ovr, qwk, map@k, rmse, rmsle (trains on log1p), mae, mape, r2

Submission format

the sample submission

probability, value, label, space-separated top-k labels, one column per class

Extra tables, text, images

other tables sharing a column with train; long free-text columns; file-path columns and media files

reported as limitations, with the join key and rows per key

Use it from Python

import tabular_ds_mcp as t

plan = t.inspect_competition("data/")                    # finds target, ID, task, metric hint, time/group structure
for call in plan["suggested_calls"]:                     # the calls it suggests already carry the right arguments
    result = getattr(t, call["tool"])(**call["args"])
    print(call["tool"], result.get("warnings"))

The Kaggle walkthrough notebook runs every step on Playground Series S6E11 (credit-card fraud) and falls back to the synthetic demo data anywhere else.

Design

  • Leakage-safe by construction. Encoders live inside a scikit-learn pipeline that is refitted on every training fold; dates are split into numeric parts and categorical columns cast to strings row by row before that.

  • Baselines everywhere. cv_baseline scores a no-skill model on the same folds, so a number never stands alone.

  • Validation that matches the test set. Time-ordered and group folds, compared fold by fold with random splits of the same rows (for time folds, with the same training size), so the tool can say when a random K-fold score cannot be trusted.

  • Plain-Python core, thin MCP layer. core.py holds all logic; server.py only exposes it, which keeps the tools testable and usable outside MCP.

  • Light dependencies. pandas, NumPy, SciPy, scikit-learn (HistGradientBoosting) and the MCP SDK.

Tests

.venv/bin/pip install -e ".[dev]" && .venv/bin/pytest

38 tests check every tool on small synthetic tables whose right answer is known: no shift vs. a planted shift, signal vs. pure noise, a random-walk target where random folds must look too good and independent rows where they must not, memorised customers, each competition metric and submission format, each kind of broken submission, folders whose suggested calls must run as written, the one-command demo, plus an end-to-end test that starts the server over stdio and calls it as an MCP client. They run on every push for Python 3.10, 3.12 and 3.13.

Privacy and safety

  • Everything runs locally; the tools make no network calls.

  • When an AI agent calls the tools, their output goes to that agent's model, including column summaries and the five most frequent values of each column. Do not point the tools at data you may not share with your model provider.

  • The tools write only .csv files (out_path, oof_path), never through a symlink.

Limitations

  • The baseline is an untuned gradient-boosting model: a reference point, not a leaderboard model.

  • Forecasting problems get time-ordered validation and date parts, but no lag or rolling features.

  • Extra tables are detected (with the join key), not joined; free text and images are not modelled.

  • Permutation importance spreads credit across correlated features.

License

MIT © 2026 Yusuf Ömer Erem

Available Tools

7 tools
check_submissionA

Check a submission file against the sample submission before uploading it: columns, row count, duplicated or missing IDs, missing values, constant predictions, the [0, 1] range for probabilities, per-row probability sums and the number of labels per row for top-k (MAP@k) submissions.

Args: submission_path: the file to upload. sample_submission_path: the competition's sample submission. test_path: optional test table, to check that every test ID is predicted. id_col: ID column (default: first column of the sample submission).

Inputs: submission_path (required), sample_submission_path (required), id_col, test_path.

compare_train_testA

Check whether the test set looks like the training set: column and dtype mismatches, unseen categories, PSI and KS per feature, an adversarial-validation AUC (0.5 = indistinguishable), whether the test rows come after the training period, and how many test rows belong to keys never seen in train.

Args: train_path: training table. test_path: test table (no target column needed). target: target column in the training table, excluded from the comparison. id_col: ID column, excluded from the comparison. time_col: time column to check (default: date columns are found automatically). group_col: key column to check, such as customer_id (default: found automatically). max_rows: sample size per table for the heavier checks.

Inputs: test_path (required), train_path (required), id_col, target, +3 more.

cv_baselineA

Cross-validated gradient-boosting baseline reported next to a no-skill baseline. Encoders are fitted inside each training fold, so the scores are free of preprocessing leakage. With time_col the folds follow time; with group_col no group is split across folds. In both cases the same model is also scored with random folds, and the tool says whether random validation would overstate the score.

Args: train_path: training table. target: target column. id_col: ID column, excluded from the features. task: 'auto', 'binary', 'multiclass' or 'regression'. metric: the competition metric. Binary: roc_auc, pr_auc, log_loss, accuracy, f1, mcc. Multiclass: log_loss, accuracy, macro_f1, roc_auc_ovr, qwk, map@3 (any k). Regression: rmse, rmsle, mae, mape, r2, qwk. Default: roc_auc / log_loss / rmse. time_col: date or time-index column; folds train on the past and score the next time block. group_col: key column (customer, store, patient...); a group never sits in both parts of a fold. n_splits: number of folds. max_rows: train on a random sample of this many rows. oof_path: optional CSV path to save out-of-fold predictions.

Inputs: target (required), train_path (required), task, id_col, +6 more.

explain_modelA

Which features matter? Permutation importance of a gradient-boosting model on a hold-out split (the latest 20% in time with time_col, 20% of the groups with group_col, else a random 20%).

Args: train_path: training table. target: target column. id_col: ID column, excluded from the features. task: 'auto', 'binary', 'multiclass' or 'regression'. time_col: hold out the latest rows by this column. group_col: hold out whole groups of this column. top_k: number of features to return. max_rows: use a random sample of this many rows.

Inputs: target (required), train_path (required), task, top_k, +4 more.

fit_predictA

Fit the baseline model on all training rows and write a submission file in the sample submission's format: one probability or value per row, a label, space-separated top-k labels (MAP@k) or one probability column per class. Run check_submission on the result before uploading.

Args: train_path: training table. test_path: test table. target: target column. id_col: ID column, copied to the submission. out_path: where to write the submission CSV. sample_submission_path: the competition's sample submission (sets the output format). task: 'auto', 'binary', 'multiclass' or 'regression'. metric: the competition metric (rmsle trains on log1p(target); map@k writes k labels). group_col: key column to leave out of the features, as in cv_baseline.

Inputs: id_col (required), target (required), out_path (required), test_path (required), +5 more.

inspect_competitionA

Start here. Read a competition or project folder and say what kind of problem it is: train / test / sample-submission files, target and ID columns, task, submission format and a likely metric, whether the test rows lie later in time or belong to new groups (customers, stores...), extra tables that need a join, image / text content, and the exact tool calls to make next.

Args: folder: directory holding the competition files (for example /kaggle/input/).

Inputs: folder (required).

profile_datasetA

Profile a CSV/Parquet table: shape, column types, missing values, cardinality, duplicate rows, target balance and warnings (constant or ID-like columns, possible target leakage, date columns, repeated keys, free-text and file-path columns).

Args: path: file path of the table. target: name of the target column, if the table has one. id_col: name of the ID column, which is excluded from the feature checks. max_rows: profile a random sample of this many rows (default: all rows).

Inputs: path (required), id_col, target, max_rows.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    The tools cover distinct stages of a tabular ML workflow, and descriptions clarify boundaries. Minor overlap exists between profile_dataset and inspect_competition (both inspect data) and among cv_baseline, explain_model, and fit_predict (all fit models), but each targets a different output.

    Naming Consistency4/5

    All names are snake_case and mostly follow a verb_noun pattern (profile_dataset, compare_train_test, explain_model, check_submission). cv_baseline is a noun phrase and fit_predict contains two verbs, but the overall style remains consistent and readable.

    Tool Count5/5

    Seven tools form a tight workflow from competition inspection to submission validation. Every tool has a clear role and none feels redundant or missing for the intended scope.

    Completeness4/5

    The surface covers inspection, profiling, train/test comparison, cross-validation, model explanation, prediction, and submission validation—the core lifecycle for tabular competitions. Minor gaps remain: no explicit tool for joining extra tables or handling multi-table relations, and no tuning or feature-engineering beyond a baseline.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Data Science Agent MCP Server

      frzzzing
      F
      license
      Not graded
      quality
      D
      maintenance
      Provides MCP-compatible tools for data analysis, including file reading, Python/SQL execution, and hypothesis testing. Enables autonomous data analysis agents to interact with a sandboxed environment.
      1
      -

    • mcp-server

      punativaishnavi
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to safely perform sandboxed file operations, evaluate math expressions, and run read-only SQL queries on a sample database, plus access resources and prompt templates.
      MIT