mlflow

MLflow MCP 服务

覆盖范围最广的 MLflow MCP——包括 MLflow 3 跟踪记录、提示词优化、Webhooks，以及其他 MCP 都不支持的 Databricks 跟踪附件。

提供 82 个工具，涵盖实验、运行、注册表、已记录模型、跟踪记录、评估、Webhooks 和提示词优化。聚合工具（summarize-experiment、summarize-run）可将 3–5 次往返请求合并为一个结构化响应，并包含已获取的指标统计数据。

它的独到之处

• 全面覆盖——唯一提供提示词优化任务（5 个工具）、Webhooks（6 个）、MLflow 3 LoggedModel（8 个）和 Databricks 跟踪附件（list-trace-attachments、get-trace-attachment）的第三方 MLflow MCP；开源版会返回 404。
• 聚合工具——summarize-experiment 可在一次调用中返回实验、前 N 个运行和指标统计（最小值/最大值/平均值），直接使用已获取的数据，无需额外往返请求。summarize-run 会对 metricHistory.history.*.key 去重（4k 个数据点的序列可节省约 100KB）。
• 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 投影；支持通过 MLFLOW_TOOLS / MLFLOW_DISABLE 配置 8 个类别；提供 search-tools 元工具。
• Apps SDK 卡片——在 ChatGPT 客户端中，compare-runs 会通过 _meta["openai/outputTemplate"] 渲染为并排卡片（运行摘要、指标/参数表格，并高亮差异）。Claude 客户端会收到相同的 JSON 内容。
• stdio + Streamable HTTP——默认使用 stdio。设置 MCP_TRANSPORT=http，即可供 ChatGPT Apps SDK 或远程客户端使用（通过 MCP_HTTP_TOKEN 进行 Bearer 身份验证）。

试试看——5 个提示词

将服务连接到 Claude Desktop 或 Claude Code，然后粘贴以下任意提示词：

1. 最佳运行——“在 customer-churn-v3 实验中，找出 val_accuracy 最高的运行。显示其超参数和指标历史。”
2. 故障模式聚类——“找出实验 12 中过去 24 小时内 status=ERROR 的跟踪记录。按异常类型对故障分组，并列出最常见的 3 种。”
3. 运行对比——“按 validation_loss 对实验 12 中排名前 5 的运行进行比较。用表格显示不同的超参数。”
4. 模型晋级——“获取已注册模型 recommendation_v2 中带有 champion 别名的最新版本。显示其训练指标，以及与源运行的沿袭关系。”
5. 跟踪记录深入分析——“提取跟踪记录 tr-abc123。标出耗时较长的 Span 和所有失败的反馈注释。”（在 Databricks 工作区中添加 list-trace-attachments。）

何时使用此工具而不是其他方案

	官方 mlflow[mcp]	kkruglik/mlflow-mcp	@us-all/mlflow-mcp（本项目）
工具数量	约 9 个（仅支持 trace）	约 25 个	78 个
MLflow 3 LoggedModel	❌	✅	✅
Trace 附件	❌	❌	✅ 仅限 Databricks
提示词优化作业	❌	❌	✅
Webhook	❌	❌	✅
聚合工具	❌	❌	✅ summarize-experiment、summarize-run
MCP 提示词	❌	✅	✅
MCP 资源	❌	❌	✅ 6 个 URI
身份验证	Databricks SDK	Bearer / basic	Bearer / basic
传输方式	stdio	stdio	stdio

官方 mlflow[mcp] 内置于 MLflow 本身，并有意将功能限制在 trace 范围内。可将它用于快速检查托管 MLflow 中的 trace。若需端到端覆盖，尤其是 MLflow 3 实体、提示词优化工作流以及基于聚合的 AI 调试，请使用本 MCP 服务。

安装

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	设为 http 以启用 Streamable 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（公开的存活状态检查）。

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，以及所有模型版本、已记录模型、trace、评估、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 上限适用于每页，而非每次调用——仍可通过分页获取完整结果集。
• 尚未在真实的 Databricks 环境中验证 Bearer / Basic 身份验证代码路径（见未完成的路线图事项）。在 OSS MLflow 3.12 上可用（Bearer 可选）。

MCP 提示词（4 个）

可通过 MCP prompts/list 使用的工作流模板：

• debug-failed-traces — 查找失败的追踪并按失败模式分组
• promote-best-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 和 summarize-experiment 接受 extractFields，用于筛选响应字段。

完整工具列表

实验（9 个）

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

运行（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 (聚合)

注册模型（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

模型版本（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

已记录的模型 — 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

追踪（8 个）

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

评估（5 个）

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

Webhook（6 个）

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

提示词优化（5 个）

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

聚合

summarize-experiment, summarize-run — 将 3–5 次往返请求整合为一个包含 caveats 数组的结构化响应。

元工具

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/基本凭据脱敏 + 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