mlflow-mcp-server

# MLflow MCP 服务器 > **最全面的 MLflow MCP — 包括 MLflow 3 跟踪、提示优化、Webhook 和 Databricks 跟踪附件，这些是其他 MCP 所不具备的。** > > 跨实验、运行、注册、已记录模型、跟踪、评估、Webhook、提示优化的 82 种工具。聚合工具（`summarize-experiment`、`summarize-run`）将 3-5 次往返折叠成一个具有预先获取的指标统计信息的结构化响应。 [](https://www.npmjs.com/package/@us-all/mlflow-mcp) [](https://www.npmjs.com/package/@us-all/mlflow-mcp) [](#tools) [](https://github.com/us-all/mcp-toolkit/blob/main/STANDARD.md) [](https://glama.ai/mcp/servers/us-all/mlflow-mcp-server) ## 它能做什么，其他的不行 - **全面覆盖** — 唯一第三方的 MLflow MCP 提供提示优化作业（5 种工具）、Webhook（6 种）、MLflow 3 已记录模型（8 种）和 Databricks 跟踪附件（`list-trace-attachments`、`get-trace-attachment` — 仅限 Databricks MLflow；开源返回 404）。 - **聚合工具** — `summarize-experiment` 返回实验 + 前 N 名运行 + 指标统计信息（最小/最大/平均值）通过一次调用从已获取的数据中获取，无需额外的往返。`summarize-run` 取消重复 `metricHistory.history.*.key`（约 100KB 节省 4k 点系列）。 - **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}`。 - **设计高效使用令牌** — `extractFields` 在 `get-run` / `search-runs` / `search-traces` / `get-trace` / 大量读取时进行投影，`MLFLOW_TOOLS` / `MLFLOW_DISABLE` 8 类别，`search-tools` 元工具。 - **应用 SDK 卡片** — `compare-runs` 在 ChatGPT 客户端上呈现为并排卡片（运行摘要 + 指标/参数表，差异高亮）通过 `_meta["openai/outputTemplate"]`。Claude 客户端接收相同的 JSON 内容。 - **stdio + 可流式 HTTP** — 默认情况下为 stdio。设置 `MCP_TRANSPORT=http` 以支持 ChatGPT 应用 SDK 或远程客户端（通过 `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 已记录模型 | ❌ | ✅ | ✅ | | 跟踪附件 | ❌ | ❌ | ✅ 仅限 Databricks | | 提示优化作业 | ❌ | ❌ | ✅ | | Webhook | ❌ | ❌ | ✅ | | 聚合工具 | ❌ | ❌ | ✅ `summarize-experiment`、`summarize-run` | | MCP 提示 | ❌ | ✅ | ✅ | | MCP 资源 | ❌ | ❌ | ✅ 6 个 URI | | 身份验证 | Databricks SDK | Bearer / 基本身份验证 | Bearer / 基本身份验证 | | 传输 | stdio | stdio | stdio | 官方的 `mlflow[mcp]` 被捆绑在 MLflow 本身内部，并且故意对跟踪范围进行限制。将它用于快速托管的 MLflow 跟踪检查。使用此服务器进行端到端覆盖，特别是 MLflow 3 实体、提示优化工作流和聚合驱动的 AI 调试。 ## 安装 ### Claude Desktop ```json { "mcpServers": { "mlflow": { "command": "npx", "args": ["-y", "@us-all/mlflow-mcp"], "env": { "MLFLOW_TRACKING_URI": "http://localhost:5000" } } } } ``` ### Claude Code ```bash claude mcp add mlflow -s user \ -e MLFLOW_TRACKING_URI=http://localhost:5000 \ -- npx -y @us-all/mlflow-mcp ``` ### Docker ```bash docker run --rm -i \ -e MLFLOW_TRACKING_URI=http://your-host:5000 \ ghcr.io/us-all/mlflow-mcp-server ``` ### 从源代码构建 ```bash 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` | ❌ | — | 基本身份验证用户名（令牌的替代方案） | | `MLFLOW_TRACKING_PASSWORD` | ❌ | — | 基本身份验证密码 | | `MLFLOW_EXPERIMENT_ID` | ❌ | — | 隐含接受它的工具的默认实验 ID | | `MLFLOW_ALLOW_WRITE` | ❌ | `false` | 设置为 `true` 以启用突变（创建/更新/删除） | | `MLFLOW_TOOLS` | ❌ | — | 类别的逗号分隔允许列表。最大的令牌节省。 | | `MLFLOW_DISABLE` | ❌ | — | 逗号分隔的禁用列表。当设置了 `MLFLOW_TOOLS` 时会被忽略。 | | `MCP_TRANSPORT` | ❌ | `stdio` | `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`（公共活动）。 ### Databricks 托管的 MLflow 对于 Databricks 托管的 MLflow： ```bash MLFLOW_TRACKING_URI=https://<workspace>.cloud.databricks.com MLFLOW_TRACKING_TOKEN=dapi... # PAT 或服务主体令牌 ``` MLflow REST API 路径（`/api/2.0/mlflow/...`）在开源和 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` 调用路由，开放源代码 MLflow（验证到 3.12.0）返回 404。工具描述显示了这一点；对开放源代码的调用返回一个结构化的 `MlflowError`。 - **`search-traces.maxResults` 限制适用于每页**，而不是每个调用 — 分页仍然可以获取完整的结果集。 - **Bearer / 基本身份验证代码路径尚未针对实时 Databricks 进行验证**（参见开放的路线图项目）。适用于开源 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`、`get-trace` 和 `summarize-experiment` 接受 `extractFields` 以进行响应切片。 <details> <summary>完整工具列表</summary> ### 实验（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` — 按关键词查询其他工具；始终启用。 </details> ## 使用 docker compose 进行本地验证 ```bash # 1. 启动 MLflow（UI 在 http://localhost:5050） docker compose up -d mlflow # 2. 种子演示实验、运行、已注册模型、跟踪 docker compose run --rm seed # 3a. 在组合的 MLflow 上本地探测 MCP 服务器 MLFLOW_TRACKING_URI=http://localhost:5050 \ MLFLOW_EXPERIMENT_ID=1 \ MLFLOW_ALLOW_WRITE=true \ node dist/index.js # 3b. 或在组合中运行（stdio） docker compose run --rm mcp # 拆除 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`](https://github.com/us-all/mcp-toolkit)： - `extractFields` — 高效的令牌响应投影 - `aggregate(fetchers, caveats)` — `summarize-experiment` 的扇出帮助程序 - `createWrapToolHandler` — Bearer/基本凭证编辑 + MlflowError 提取 - `search-tools` 元工具 针对 MLflow 3.5.1+（使用 v3 跟踪/评估 REST）。开发组合固定为 MLflow 3.12.0（多模态跟踪附件 + 分页跟踪搜索）。 ## 技术栈 Node.js 22+ • TypeScript 严格 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](./LICENSE)