compare_runs
Compare runs side-by-side with full metrics and params. Runs can be large — keep the list short.
LABSCO SUMMARY
Registry work that normally means a notebook cell becomes one call — including the irreversible kind.
The read surface is unusually careful about context: get_runs, query_runs and search_runs_by_tags each state in their own descriptions that runs are large and ask you to keep limits small. Promotion follows the MLflow 3 pattern through set_model_alias and copy_model_version, while transition_model_version_stage is marked deprecated since MLflow 2.9 and kept for stage-based deployments. The delete tools have no confirmation step, and delete_model_version and delete_registered_model both say the removal cannot be recovered — unlike delete_run and delete_experiment, which move to a lifecycle stage the MLflow API can still reach.
What it is
A client for an MLflow tracking server, 40 tools across experiments, runs, artifacts and the model registry.
What you get
- Experiment access — list them, search by filter string with a sort order, fetch one by name, and read the metric names, parameter names and tag keys used across its runs.
- Run queries at several levels: runs for an experiment, one run in full, a nested run's parent, MLflow filter-syntax queries, tag search, and the best run by a named metric.
- Metric detail — latest values for a run, the full history of a single metric, and a side-by-side comparison across runs.
- Artifacts: browse a run's artifact tree, download one to a local path, or read a text or JSON artifact's content directly.
- Registry reads — registered models, every version of one, a version by number or by alias, and the latest version per stage.
- Registry writes: register a model from a URI, assign aliases, tag models, runs and experiments, update a version description, copy a version into another model, and transition stages for legacy deployments.
- Deletion for aliases, model versions, registered models, runs and experiments, plus a health check on the tracking server.
Requirements
An MLflow tracking server, addressed by MLFLOW_TRACKING_URI.
Setup effort
One command — uvx mlflow-mcp
USE CASES
01
Working out which training run actually won
Open the experiment by name, take the best run by the metric you care about, and set it beside its rivals with full metrics and params.
02
Explaining why last night's run came out worse
Query the experiment for the runs that regressed, open one in full, follow a single metric's history, and step up to the parent when the run was nested.
03
Promoting a model without opening a notebook
Register the artifact into the registry, move the champion alias onto the new version, and read the alias back to confirm what production now points at.
04
Recovering the exact config a model was trained with
Browse the run's artifact tree, read a text or JSON config straight out of it, and download anything that has to land on disk.
05
Clearing out an experiment that filled up with junk runs
Find the runs by the tags that mark them, remove them, and drop the experiment itself when nothing worth keeping is left.
06
Tracking down a model somebody else registered
List what is in the registry, read the versions of the one that looks right, and check which version each stage currently resolves to.
40 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
copy_model_version
Promote a model version to another registered model (MLflow 3 promotion pattern). Creates the destination model if it doesn't exist.
Args: src_model_name: Source registered model name. src_version: Source model version number. dst_model_name: Destination registered model name, e.g. 'my-model-prod'.
Examples: copy_model_version("my-model-dev", "3", "my-model-prod")
delete_experiment
Delete an experiment and all its runs. Moves to the 'deleted' lifecycle stage — not shown in UI or queries, but recoverable via the MLflow API.
Args: experiment_id: The experiment ID to delete.
delete_model_alias
Remove an alias from a registered model (e.g. revoke 'champion'). The alias is permanently removed; the model version itself is not affected.
Args: name: Name of the registered model. alias: Alias to remove, e.g. 'champion', 'production'.
delete_model_version
Delete a specific model version from the registry. Irreversible — the version and its metadata cannot be recovered.
Args: name: Name of the registered model. version: Version number to delete.
delete_registered_model
Delete an entire registered model and all its versions. Irreversible — all versions, aliases, and tags are permanently removed.
Args: name: Name of the registered model to delete.
delete_run
Delete a run. Moves it to the 'deleted' lifecycle stage — not shown in UI or queries, but recoverable via the MLflow API.
Args: run_id: The run ID to delete.
get_artifact_content
Read and return artifact content (for text/json files)
get_best_run
Get the best run by a specific metric (e.g., highest accuracy, lowest loss). Works with metrics containing special characters like '/' (e.g., 'trading/total_profit')
get_experiment_by_name
Get experiment details by name (more convenient than ID)
get_experiment_metrics
Get all unique metric names used across all runs in an experiment
get_experiment_params
Get all unique parameter names used across all runs in an experiment
get_experiment_tags
Get all unique tag keys used across all runs in an experiment
get_experiments
Get all experiments
get_latest_versions
Get latest model versions for each stage (e.g. 'Staging', 'Production').
Args: name: Name of the registered model. stages: List of stages to filter by, e.g. ['Production', 'Staging']. If None, returns latest version for all stages.
get_logged_model
Get detailed information about a specific logged model by its ID.
Args: model_id: The logged model ID (obtained from search_logged_models results).
get_model_version
Get specific model version details (metrics, stage, run_id)
get_model_version_by_alias
Get a model version by its alias (e.g. 'champion', 'production').
Args: name: Name of the registered model. alias: The alias assigned to the version, e.g. 'champion'.
get_model_versions
Get all versions of a registered model
get_parent_run
Get the parent run of a nested run. Returns None if the run has no parent.
Args: run_id: The child run ID to find the parent for.
get_registered_model
Get full details of a registered model including all versions and aliases. Can be large for models with many versions.
Args: name: Name of the registered model.
get_registered_models
List all registered models in the model registry
get_run
Get detailed information about a specific run. Run data can be large — avoid fetching many runs at once.
get_run_artifact
Download and return the local path to a specific artifact
get_run_artifacts
List artifacts for a specific run. Use 'path' to browse into directories (e.g., 'configs')
get_run_metric
Get the full history of a specific metric for a run
get_run_metrics
Get all metrics for a specific run with their latest values
get_runs
Get runs for a specific experiment with full details.
Each run contains full metrics, params, and tags — keep limit small (3-10) to avoid flooding context. Use offset to paginate.
Args: experiment_id: The experiment ID limit: Maximum number of runs to return. Keep small — each run is large. offset: Number of runs to skip order_by: List of sort clauses, e.g. ['metrics.rmse DESC', 'params.lr ASC']. Use backticks for special characters: ['metrics.trading/loss DESC']
Examples: get_runs("1", limit=5) get_runs("1", order_by=["metrics.accuracy DESC"])
health
Check MLflow server health and connectivity
query_runs
Query runs using MLflow's filter syntax with optional sorting.
Runs can be large. Use wise limits to avoid flooding context.
Args: experiment_id: The experiment ID query: MLflow filter string (e.g., 'metrics.accuracy > 0.9') limit: Maximum number of runs to return offset: Number of runs to skip order_by: List of sort clauses, e.g. ['metrics.rmse DESC', 'params.lr ASC']. Use backticks for special characters: ['metrics.trading/loss DESC']
Examples: query_runs("1", "metrics.accuracy > 0", order_by=["metrics.accuracy DESC"]) query_runs("1", "", order_by=["metrics.f1/score DESC"])
register_model
Register a model into the model registry. Creates the registered model if it doesn't exist.
Args: model_name: Name for the registered model. model_uri: URI of the model to register. Supports:
- LoggedModel: 'models:/m-abc123'
- Run artifact: 'runs:/run_id/artifact_path' tags: Optional dict of tags to set on the model version.
Examples: register_model("btc-classifier", "models:/m-abc123") register_model("btc-classifier", "runs:/abc123/model", tags={"framework": "lightgbm"})
search_experiments
Search experiments with optional filtering and sorting.
Args: filter_string: Filter query, e.g. "name LIKE 'btc%'" or "tags.team = 'ml'". Supports name, creation_time, last_update_time, tags.<key>. order_by: List of sort clauses, e.g. ["last_update_time DESC", "name ASC"]. max_results: Maximum number of experiments to return (default 100).
Examples: search_experiments(filter_string="name LIKE 'btc%'") search_experiments(order_by=["last_update_time DESC"])
search_logged_models
Search for logged models across one or more experiments. Results can be large — use wise limits.
Args: experiment_ids: List of experiment IDs to search in (at least one required). filter_string: SQL-like filter, e.g. 'metrics.accuracy > 0.9' or "tags.release = 'v1.0'". Multiple conditions use AND only (OR not supported). max_results: Maximum number of models to return (default 5). datasets: Filter by datasets the model was evaluated on. Each dict must include 'name' (str) and 'digest' (str), e.g. [{'name': 'val', 'digest': 'abc123'}]. order_by: List of sort clauses, each a dict with 'field_name' (str) and 'ascending' (bool), e.g. [{'field_name': 'metrics.accuracy', 'ascending': False}].
Examples: search_logged_models(["1"], filter_string="metrics.accuracy > 0.9") search_logged_models(["1", "2"], order_by=[{"field_name": "metrics.f1", "ascending": False}])
search_runs_by_tags
Find runs with specific tags (e.g., {'team': 'nlp', 'production': 'true'}). Runs can be large — use wise limits.
set_experiment_tag
Set a tag on an experiment.
Args: experiment_id: The experiment ID to tag. key: Tag key, e.g. 'team', 'status'. value: Tag value.
set_model_alias
Assign an alias to a specific model version (e.g. promote best model to 'champion').
Args: name: Name of the registered model. alias: Alias to assign, e.g. 'champion', 'production', 'baseline'. version: Model version number to assign the alias to.
Examples: set_model_alias("lightgbm", "champion", "3")
set_registered_model_tag
Set a tag on a registered model (e.g. problem_type, team, framework).
Args: name: Name of the registered model. key: Tag key, e.g. 'problem_type', 'team', 'framework'. value: Tag value.
set_run_tag
Set a tag on a run (e.g. annotate best model, flag for review).
Args: run_id: The run ID to tag. key: Tag key, e.g. 'best_model', 'reviewed_by'. value: Tag value.
transition_model_version_stage
Transition a model version to a new stage (Staging, Production, Archived).
Deprecated since MLflow 2.9. Prefer aliases (set_model_alias) and copy_model_version for MLflow 3+ workflows. Use this only when working with legacy stage-based deployments.
Args: name: Name of the registered model. version: Model version number. stage: Target stage: 'Staging', 'Production', or 'Archived'. archive_existing: If True, archive existing versions in the target stage.
update_model_version
Update the description of a model version.
Args: name: Name of the registered model. version: Model version number. description: New description text.
BEFORE YOU INSTALL
What to know first
Tools you get
40 tools when we connected. compare_runs_by_ids, find_best_run, promote_best_model and audit_mlflow_setup are prompts, not tools. Destructive tools such as delete_run and delete_registered_model are included, and transition_model_version_stage is deprecated since MLflow 2.9.
Requires
- uvx on PATH
- Python >=3.10
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Moderate Standing cost
Rated by the size of the 40 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx mlflow-mcpMCP Clients
Claude Desktop, Claude Code
JSON
{
"mcpServers": {
"mlflow": {
"command": "uvx",
"args": [
"mlflow-mcp"
],
"env": {
"MLFLOW_TRACKING_URI": "http://localhost:5000"
}
}
}
}
