mlflow

MLflow MCP サーバー

MLflow 3 のトレース、プロンプト最適化、Webhook、そして他のどの MCP も公開していない Databricks のトレース添付ファイルまで網羅する、最も幅広いカバレッジの MLflow MCP です。

実験、実行、レジストリ、ログ記録済みモデル、トレース、評価、Webhook、プロンプト最適化にわたる 82 個のツールを提供します。集約ツール（summarize-experiment、summarize-run）は、取得済みのメトリクス統計を含む構造化レスポンスに、3～5 回のラウンドトリップをまとめます。

他にはない機能

• 完全なカバレッジ — プロンプト最適化ジョブ（5 個のツール）、Webhook（6 個）、MLflow 3 の LoggedModel（8 個）、Databricks のトレース添付ファイル（list-trace-attachments、get-trace-attachment。Databricks MLflow のみ対応。OSS では 404 を返します）を提供する唯一のサードパーティー製 MLflow MCP です。
• 集約ツール — summarize-experiment は、取得済みデータから実験、上位 N 件の実行、メトリクス統計（最小値／最大値／平均値）を 1 回の呼び出しで返し、追加のラウンドトリップは不要です。summarize-run は metricHistory.history.*.key の重複を排除します（4,000 ポイントの系列で約 100 KB の削減）。
• MCP プロンプト（4 個）— debug-failed-traces、promote-best-run、compare-top-runs、annotate-trace-quality。モデルが直接呼び出すワークフローテンプレートです。
• MCP リソース（6 個）— mlflow://run/{runId}、mlflow://experiment/{expId}、mlflow://run/{runId}/artifacts、mlflow://experiment/{expId}/runs、mlflow://registered-model/{name}/versions、mlflow://trace/{traceId}。
• トークン効率を考慮した設計 — get-run／search-runs／search-traces／get-trace／大容量の読み取りに対する extractFields 投影、8 カテゴリの MLFLOW_TOOLS／MLFLOW_DISABLE、メタツールの search-tools を提供します。
• Apps SDK カード — ChatGPT クライアントでは _meta["openai/outputTemplate"] を通じて、compare-runs が横並びのカード（実行の概要と、差分をハイライト表示するメトリクス／パラメーターの表）としてレンダリングされます。Claude クライアントには同じ JSON コンテンツが返されます。
• stdio ＋ Streamable HTTP — デフォルトは stdio です。ChatGPT Apps SDK またはリモートクライアントを利用する場合は、MCP_TRANSPORT=http を設定してください（MCP_HTTP_TOKEN による Bearer 認証）。

試してみましょう — 5 つのプロンプト

サーバーを Claude Desktop または Claude Code に接続し、次のいずれかを貼り付けてください。

1. 最良の実行 — 「customer-churn-v3 実験で、val_accuracy が最も高い実行を見つけてください。ハイパーパラメーターとメトリクスの履歴を表示してください。」
2. 失敗パターンのクラスタリング — 「実験 12 で過去 24 時間に発生した status=ERROR のトレースを見つけてください。例外の種類ごとに失敗をグループ化し、最も多いものを 3 つ表示してください。」
3. 実行の比較 — 「実験 12 の上位 5 件の実行を validation_loss で比較してください。異なるハイパーパラメーターを表に表示してください。」
4. モデルの昇格 — 「champion エイリアスが付いた登録済みモデル recommendation_v2 の最新バージョンを取得してください。トレーニングのメトリクスと、ソース実行までのリネージを表示してください。」
5. トレースの詳細調査 — 「トレース tr-abc123 を取得してください。遅いスパンと、失敗したフィードバック注釈があれば強調表示してください。」（Databricks ワークスペースでは list-trace-attachments を追加してください。）

このサーバーと代替手段の使い分け

	公式の mlflow[mcp]	kkruglik/mlflow-mcp	@us-all/mlflow-mcp（本サーバー）
ツール数	約9個（トレースのみ）	約25個	78個
MLflow 3 の LoggedModel	❌	✅	✅
トレースの添付ファイル	❌	❌	✅ Databricks のみ
プロンプト最適化ジョブ	❌	❌	✅
Webhook	❌	❌	✅
集約ツール	❌	❌	✅ summarize-experiment、summarize-run
MCP プロンプト	❌	✅	✅
MCP リソース	❌	❌	✅ 6 個の URI
認証	Databricks SDK	Bearer／basic	Bearer／basic
トランスポート	stdio	stdio	stdio

公式の mlflow[mcp] は MLflow 自体にバンドルされており、意図的にトレースに特化しています。マネージド MLflow のトレースを手早く確認する場合に使用してください。エンドツーエンドのカバレッジ、特に MLflow 3 のエンティティ、プロンプト最適化ワークフロー、集約を活用した AI デバッグには、このサーバーを使用してください。

インストール

Claude Desktop

{
  "mcpServers": {
    "mlflow": {
      "command": "npx",
      "args": ["-y", "@us-all/mlflow-mcp"],
      "env": {
        "MLFLOW_TRACKING_URI": "http://localhost:5000"
      }
    }
  }
}

Claude Code

claude mcp add mlflow -s user \
  -e MLFLOW_TRACKING_URI=http://localhost:5000 \
  -- npx -y @us-all/mlflow-mcp

Docker

docker run --rm -i \
  -e MLFLOW_TRACKING_URI=http://your-host:5000 \
  ghcr.io/us-all/mlflow-mcp-server

ソースからビルド

git clone https://github.com/us-all/mlflow-mcp-server.git
cd mlflow-mcp-server && pnpm install && pnpm build
node dist/index.js

設定

変数	必須	デフォルト	説明
MLFLOW_TRACKING_URI	✅	—	MLflow のトラッキング URL（http://localhost:5000、Databricks ワークスペース URL など）
MLFLOW_TRACKING_TOKEN	❌	—	Bearer トークン。Databricks PAT（dapi…）に使用します
MLFLOW_TRACKING_USERNAME	❌	—	Basic 認証のユーザー名（トークンの代わりに使用）
MLFLOW_TRACKING_PASSWORD	❌	—	Basic 認証のパスワード
MLFLOW_EXPERIMENT_ID	❌	—	明示的な指定が可能なツールで使用する、デフォルトの実験 ID
MLFLOW_ALLOW_WRITE	❌	false	変更（作成／更新／削除）を有効にするには true を設定します
MLFLOW_TOOLS	❌	—	カテゴリのカンマ区切り許可リスト。トークンを大幅に節約できます
MLFLOW_DISABLE	❌	—	カテゴリのカンマ区切り拒否リスト。MLFLOW_TOOLS が設定されている場合は無視されます
MCP_TRANSPORT	❌	stdio	Streamable HTTP トランスポートを有効にするには http を指定します
MCP_HTTP_TOKEN	条件付き	—	Bearer トークン。MCP_TRANSPORT=http の場合に必須です
MCP_HTTP_PORT	❌	3000	HTTP のリッスンポート
MCP_HTTP_HOST	❌	127.0.0.1	HTTP のバインドホスト（localhost では DNS リバインディング保護が自動的に有効になります）
MCP_HTTP_SKIP_AUTH	❌	false	Bearer 認証をスキップします。認証を処理するリバースプロキシの背後にある場合などに使用します

カテゴリ（8）：experiments、runs、registry、logged-models、traces、assessments、webhooks、prompts。

MCP_TRANSPORT=http の場合：POST /mcp（Bearer 認証付き JSON-RPC）と GET /health（公開 liveness エンドポイント）。

Databricks のマネージド MLflow

Databricks でホストされている MLflow の場合：

MLFLOW_TRACKING_URI=https://<workspace>.cloud.databricks.com
MLFLOW_TRACKING_TOKEN=dapi...   # PAT or service-principal token

MLflow REST API のパス（/api/2.0/mlflow/...）は、OSS と Databricks で同一です。Bearer 認証は PAT とサービスプリンシパルのどちらのフローにも対応します。

トークン効率

シナリオ	ツール数	スキーマトークン数	デフォルト比
デフォルト（すべてのカテゴリ）	78	9,200	—
一般的な設定（MLFLOW_TOOLS=experiments,runs,registry,traces）	54	5,900	−36%
限定的な設定（MLFLOW_TOOLS=experiments,runs）	27	3,200	−66%

さらに、get-run／search-runs／search-traces／get-trace／summarize-experiment では extractFields を使用できます。呼び出しごとに、呼び出し元がレスポンスのフィールドを指定できます。

読み取り専用モード

デフォルトでは、すべての書き込みがブロックされます。次の操作には MLFLOW_ALLOW_WRITE=true が必要です。

create-experiment、update-experiment、delete-experiment、restore-experiment、set-experiment-tag、delete-experiment-tag、create-run、update-run、delete-run、restore-run、log-metric、log-param、log-batch、log-inputs、set-run-tag、delete-run-tag、create-registered-model、rename-registered-model、update-registered-model、delete-registered-model、およびすべてのモデルバージョン、ログ記録済みモデル、トレース、評価、Webhook、プロンプト最適化に関する書き込み操作。

制限事項と注意点

• search-traces.maxResults は最大 500 に制限されます。 MLflow 3.12 以降では、ページごとの max_results > 500 が INVALID_PARAMETER_VALUE で拒否されます。より大きな結果セットを取得するには、nextPageToken を使って繰り返し取得してください。トレースの総数に上限はありません。
• トレースの添付ファイルは Databricks 専用です。 list-trace-attachments ／ get-trace-attachment は、OSS MLflow（3.12.0 まで確認済み）では 404 を返すルートを呼び出します。ツールの説明にもこの点が記載されており、OSS に対する呼び出しは構造化された MlflowError を返します。
• search-traces.maxResults の上限は、呼び出しごとではなくページごとに適用されます。 ページネーションを使えば、引き続き全件を取得できます。
• Bearer ／ Basic 認証のコードパスは、実稼働中の Databricks に対してまだ検証されていません（未完了のロードマップ項目を参照）。OSS MLflow 3.12 では動作します（Bearer は任意）。

MCP プロンプト（4 件）

MCP の prompts/list から利用できるワークフローテンプレートです。

• debug-failed-traces — 失敗したトレースを見つけ、失敗パターンごとにグループ化します
• promote-best-run — 最良の run を見つけて登録し、champion エイリアスを設定します
• compare-top-runs — メトリクス別に上位 N 件を比較します
• annotate-trace-quality — ガイド付きのフィードバック注釈ループです

MCP リソース

URI ベースの読み取り専用アクセスです。

mlflow://run/{runId}, mlflow://experiment/{expId}, mlflow://experiment-by-name/{name}, mlflow://registered-model/{name}, mlflow://model-version/{name}/{version}, mlflow://trace/{traceId}, mlflow://run/{runId}/artifacts, mlflow://experiment/{expId}/runs, mlflow://registered-model/{name}/versions。

ツール（82 件）

8 つのカテゴリがあります。実行時にツールを見つけるには search-tools を使ってください。全リストは以下に折りたたまれています。

get-run、search-runs、search-traces、get-trace、summarize-experiment は、レスポンスの一部を抽出する extractFields を受け付けます。

ツールの全リスト

Experiments（9 件）

create-experiment、search-experiments、get-experiment、get-experiment-by-name、update-experiment、delete-experiment、restore-experiment、set-experiment-tag、delete-experiment-tag

Runs（18 件）

create-run、get-run、search-runs、update-run、delete-run、restore-run、log-metric、log-param、log-batch、log-inputs、get-metric-history、set-run-tag、delete-run-tag、list-artifacts、get-best-run、compare-runs、search-runs-by-tags、summarize-run (集計)

Registered Models（12 件）

create-registered-model、get-registered-model、search-registered-models、rename-registered-model、update-registered-model、delete-registered-model、get-latest-model-versions、set-registered-model-tag、delete-registered-model-tag、set-registered-model-alias、delete-registered-model-alias、get-model-version-by-alias

Model Versions（9 件）

create-model-version、get-model-version、search-model-versions、update-model-version、delete-model-version、transition-model-version-stage、get-model-version-download-uri、set-model-version-tag、delete-model-version-tag

Logged Models — MLflow 3（8 件）

create-logged-model、search-logged-models、get-logged-model、finalize-logged-model、delete-logged-model、set-logged-model-tags、delete-logged-model-tag、log-logged-model-params

Traces（8 件）

search-traces、get-trace、get-trace-info、delete-traces、set-trace-tag、delete-trace-tag、list-trace-attachments、get-trace-attachment

Assessments（5 件）

log-feedback、log-expectation、get-assessment、update-assessment、delete-assessment

Webhooks（6 件）

create-webhook、list-webhooks、get-webhook、update-webhook、delete-webhook、test-webhook

Prompt Optimization（5 件）

create-prompt-optimization-job、get-prompt-optimization-job、search-prompt-optimization-jobs、cancel-prompt-optimization-job、delete-prompt-optimization-job

Aggregations

summarize-experiment、summarize-run — 3～5 回の往復処理を、caveats 配列を含む 1 つの構造化レスポンスにまとめます。

Meta

search-tools — キーワードで他のツールを検索します。常に有効です。

## docker compose を使用したローカル検証

# 1. start MLflow (UI at http://localhost:5050)
docker compose up -d mlflow

# 2. seed demo experiment, runs, registered model, traces
docker compose run --rm seed

# 3a. probe the MCP server locally against the compose'd MLflow
MLFLOW_TRACKING_URI=http://localhost:5050 \
  MLFLOW_EXPERIMENT_ID=1 \
  MLFLOW_ALLOW_WRITE=true \
  node dist/index.js

# 3b. or run inside compose (stdio)
docker compose run --rm mcp

# tear down
docker compose down -v

./dev/seed.py は冪等です。demo 実験に実行がすでに存在する場合はスキップします。

アーキテクチャ

Claude → MCP stdio → src/index.ts → src/tools/*.ts → MlflowClient (fetch) → MLflow REST API

@us-all/mcp-toolkit を基盤としています。

• extractFields — トークン効率の高いレスポンスのプロジェクション
• aggregate(fetchers, caveats) — summarize-experiment 用のファンアウトヘルパー
• createWrapToolHandler — Bearer／basic 認証情報の秘匿と MlflowError の抽出
• search-tools メタツール

MLflow 3.5.1 以降を対象としています（v3 traces／assessments REST を使用）。開発用 compose は MLflow 3.12.0 に固定されています（マルチモーダルな trace 添付ファイルとページネーション対応の trace 検索）。

技術スタック

Node.js 22 以降 • TypeScript strict ESM • pnpm • @modelcontextprotocol/sdk • zod • dotenv • vitest。

参考資料

• MLflow MCP の概要：https://mlflow.org/docs/latest/genai/mcp/
• MLflow REST API：https://mlflow.org/docs/latest/api_reference/rest-api.html

ライセンス

MIT