Mlagents MCP Server

mlagents mcp

用于控制Unity ML代理训练的MCP服务器从Claude Code运行。

启动、停止、恢复、监视、比较和导出ML代理培训——所有这些都可以通过自然对话完成，而无需离开编辑器。

特性

• 训练控制 --启动、停止、恢复作为后台进程运行
• 即时检查 --在不打断对话的情况下检查培训进度
• 实时监控 --实时读取TensorBoard指标、奖励曲线和训练日志
• 运行比较 --跨运行比较度量以进行超参数调整
• 配置管理 --读取并深度合并更新YAML训练配置
• 模型导出 --定位.onx模型和检查点
• 两种训练模式 --Unity编辑器（交互式）和内置可执行文件（无头批处理）

需求

• Python 3.10+
• 紫外线 包管理器
• Unity ML代理 mlagents-learn 在PATH中可用（或通过conda env）
• 克劳德代码 命令行界面

安装

git clone https://github.com/limam-B/mlagents-mcp-server.git
cd mlagents-mcp-server
uv sync

使用Claude Code快速设置

# Register the MCP server:
claude mcp add --scope project --transport stdio mlagents-training \
  -- uv run --directory /path/to/mlagents-mcp-server mlagents-mcp

# Unregister (from all scopes to clean up stale configs):
claude mcp remove --scope local mlagents-training
claude mcp remove --scope user mlagents-training
claude mcp remove --scope project mlagents-training

# List registered servers:
claude mcp list

有环境变量

服务器从环境变量中读取其配置。将它们添加到您的 .mcp.json （项目级别）或通过CLI传递它们：

{
  "mcpServers": {
    "mlagents-training": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mlagents-mcp-server", "mlagents-mcp"],
      "env": {
        "MLAGENTS_PROJECT_ROOT": "/path/to/your/unity/project",
        "MLAGENTS_RESULTS_DIR": "results",
        "MLAGENTS_CONFIG_DIR": "config"
      }
    }
  }
}

使用conda（如果ML代理安装在conda环境中）

{
  "mcpServers": {
    "mlagents-training": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mlagents-mcp-server", "mlagents-mcp"],
      "env": {
        "MLAGENTS_PROJECT_ROOT": "/path/to/your/unity/project",
        "MLAGENTS_RESULTS_DIR": "results",
        "MLAGENTS_CONFIG_DIR": "config",
        "MLAGENTS_CONDA_ENV": "mlagents",
        "MLAGENTS_CONDA_PATH": "/home/user/miniconda3"
      }
    }
  }
}

环境变量

工具（18）

训练控制

监控

比较和导出

配置

等待并检查

这 check_* 工具 总是立即返回 --他们从不打断谈话。使用 wait_for_completion 当你想封锁直到跑步结束时（例如，封锁技能a→ 技能B自动）。

两种训练模式

编辑器模式（否 env_path)

培训连接到Unity编辑器。 force_training 块直到 mlagents-learn 打印“正在端口上监听…按播放”，然后您（或AI代理）在Unity中按播放。

force_training(config_path="movement.yaml", run_id="Movement_v1")
# → blocks until "Listening on port 5004. Start training by pressing Play..."

批处理模式（带 env_path)

Training直接启动构建的可执行文件，无需Unity编辑器。 force_training 直到可执行文件连接为止。

force_training(
    config_path="movement.yaml",
    run_id="Movement_v1",
    env_path="/path/to/Build.x86_64",
    num_envs=12,
    no_graphics=True,
)
# → blocks until "Connected to Unity environment"

工作流程示例

典型的自动化培训课程：

1. force_training(config, run_id, ...)     # launch, blocks until ready
2. wait_for_first_metrics(run_id)          # blocks until data flowing
3. wait_for_completion(run_id)             # blocks until training ends (hours)
4. export_model(run_id)                    # get checkpoint
5. update_config(next_skill, init_path=..) # chain checkpoint to next skill
6. [repeat from step 1 for next skill]

启动过程中，步骤1-2会短暂停止。第3步是整个持续时间（小时）的块——用于自动链接。对于手动监控，请使用 check_step/check_completion 而不是步骤3。

发展

# Install dev dependencies:
uv sync --group dev

# Lint:
uv run ruff check src/

# Format:
uv run ruff format src/

# Run the server directly (stdio):
uv run mlagents-mcp

项目结构

src/mlagents_mcp/
  server.py            # FastMCP app, all 18 tool definitions, entry point
  process_manager.py   # Subprocess launch/stop, log capture, port assignment
  metrics_reader.py    # TensorBoard event file parsing
  config_manager.py    # YAML config read/write/deep-merge
  run_registry.py      # Thread-safe run tracking + historical disk scan
  waiters.py           # Blocking wait logic for all wait_for_* tools
  types.py             # Shared dataclasses and enums

许可证

麻省理工学院