MLflow MCP Server

Servidor MCP do MLflow

Um servidor Model Context Protocol (MCP) que expõe operações de rastreamento de experimentos e registro de modelos do MLflow como ferramentas para assistentes de IA.

Sumário

• Início Rápido
• Ferramentas
• Exemplos de Prompts
• Configuração
• Instalação (Desenvolvimento)
• Estrutura do Projeto
• Licença

Início Rápido

A maneira mais rápida de começar é adicionar o servidor à configuração do seu cliente MCP. Não é necessário clonar localmente.

Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mlflow": {
      "command": "uvx",
      "args": ["mlflow-mcp-server"],
      "env": {
        "MLFLOW_TRACKING_URI": "http://localhost:5000"
      }
    }
  }
}

Cursor

Adicione em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mlflow": {
      "command": "uvx",
      "args": ["mlflow-mcp-server"],
      "env": {
        "MLFLOW_TRACKING_URI": "http://localhost:5000"
      }
    }
  }
}

OpenCode

Adicione ao seu opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mlflow": {
      "type": "local",
      "command": ["uvx", "mlflow-mcp-server"],
      "environment": {
        "MLFLOW_TRACKING_URI": "http://localhost:5000"
      }
    }
  }
}

Substitua http://localhost:5000 pela URL do seu servidor de rastreamento do MLflow.

Ferramentas

Gerenciamento de Experimentos

Ferramenta	Descrição
get_experiment	Obter detalhes do experimento por ID
get_experiment_by_name	Obter detalhes do experimento por nome
search_experiments	Listar e filtrar experimentos com correspondência opcional de nome e paginação

Gerenciamento de Execuções

Ferramenta	Descrição
get_run	Obter detalhes completos da execução, incluindo métricas, parâmetros, tags e tipo de execução (pai/filho/independente)
get_experiment_runs	Listar execuções de um experimento com paginação

Registro de Modelos

Ferramenta	Descrição
get_registered_models	Pesquisar e listar modelos registrados
get_model_versions	Navegar pelas versões do modelo com filtros
create_registered_model	Criar um novo modelo registrado com descrição e tags opcionais
create_model_version	Criar uma nova versão de modelo a partir dos artefatos de uma execução
rename_registered_model	Renomear um modelo registrado existente
set_registered_model_alias	Atribuir um alias (ex.: champion, challenger) a uma versão do modelo
delete_registered_model	Excluir um modelo registrado e todas as suas versões
delete_model_version	Excluir uma versão específica do modelo

Exemplos de Prompts

Depois de configurado, você pode pedir ao seu assistente de IA coisas como:

Explorando experimentos e execuções:

• "Liste todos os experimentos relacionados a modelos de recomendação"
• "Mostre-me as execuções do experimento 12 e compare suas métricas"
• "Obtenha os parâmetros e métricas da execução abc123"
• "Quais execuções no experimento de detecção de fraude têm a maior precisão?"

Gerenciando o registro de modelos:

• "Mostre-me todos os modelos registrados"
• "Registre um novo modelo chamado churn-classifier com a descrição 'Classificador binário para churn de clientes'"
• "Crie uma nova versão do churn-classifier a partir da execução abc123"
• "Defina o alias champion na versão 3 do churn-classifier"
• "Renomeie o modelo old-name para new-name"
• "Exclua a versão 1 do churn-classifier"

Análise e comparação:

• "Compare as últimas 5 execuções do experimento de ranking de busca por NDCG e latência"
• "Quais hiperparâmetros foram usados na execução de melhor desempenho do experimento 7?"
• "Liste todas as versões do modelo recommendation-model e seus aliases"

Configuração

Variável de Ambiente	Padrão	Descrição
MLFLOW_TRACKING_URI	http://localhost:5000	URL do servidor de rastreamento do MLflow

Instalação (Desenvolvimento)

Pré-requisitos

• Python 3.11+
• uv
• Um servidor de rastreamento do MLflow

Configuração

git clone https://github.com/yesid-lopez/mlflow-mcp-server.git
cd mlflow-mcp-server
uv sync

Executando Localmente

export MLFLOW_TRACKING_URI="http://localhost:5000"
uv run -m mlflow_mcp_server

O servidor se comunica via stdio, que é o transporte MCP padrão para servidores de ferramentas locais.

Estrutura do Projeto

mlflow_mcp_server/
├── __main__.py              # Entry point
├── server.py                # MCP server setup and tool registration
├── tools/
│   ├── experiment_tools.py  # Experiment search and retrieval
│   ├── run_tools.py         # Run details and listing
│   └── registered_models.py # Model registry CRUD operations
└── utils/
    └── mlflow_client.py     # MLflow client singleton

Adicionando Novas Ferramentas

1. Crie uma função no arquivo apropriado em tools/.
2. Registre-a em server.py:

from mlflow_mcp_server.tools.your_module import your_function
mcp.add_tool(your_function)

Linting

uv run ruff check .
uv run ruff format --check .

Licença

MIT