AI Gaming Agent MCP

AI游戏代理MCP服务器

MCP（模型上下文协议）服务器，使克劳德等人工智能代理能够远程控制游戏PC进行自动游戏。

Master Claude (Orchestrator)
    |
    | MCP Protocol (JSON-RPC over HTTP/SSE)
    |
    +---> PC #1 (MCP Server :8765) --> PyAutoGUI + Optional VLM
    +---> PC #2 (MCP Server :8765) --> PyAutoGUI + Optional VLM
    +---> PC #N (MCP Server :8765) --> PyAutoGUI + Optional VLM

特性

• 24个MCP工具：屏幕截图、鼠标/键盘控制、文件操作、系统命令、工作流自动化
• 工作流自动化：将多个操作链接到单个命令中 run_workflow 和 demo_terminal_workflow
• 多显示器支持：针对特定监视器进行屏幕截图和操作
• 双重运输模式：HTTP/SSE用于远程控制，stdio用于本地客户端
• 可选本地VLM：使用Olama（Qwen2.5-VL，Moondream）进行快速本地屏幕分析
• 安全第一：承载令牌身份验证、路径限制、命令阻止列表、审计日志记录
• 交叉平台的：具有自动检测功能的Windows、Linux、macOS

快速开始

安装

pip install ai-gaming-agent

或者从源代码安装：

git clone https://github.com/developerz-ai/ai-gaming-agent-mcp.git
cd ai-gaming-agent-mcp
pip install -e .

启动服务器

服务器支持两种传输模式：

HTTP/SSE传输（建议用于远程控制）：

gaming-agent serve --transport http --port 8765 --password your-secret-password

标准传输（适用于本地MCP客户端）：

gaming-agent serve --transport stdio

从克劳德桌面连接

对于HTTP/SSE传输：

添加到您的Claude桌面配置(~/.config/claude/claude_desktop_config.json 在Linux上， ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "gaming-pc": {
      "transport": "sse",
      "url": "http://YOUR-PC-IP:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-password"
      }
    }
  }
}

对于标准运输：

{
  "mcpServers": {
    "gaming-pc": {
      "command": "gaming-agent",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

快速测试

使用单个命令测试完整的自动化能力：

# Start the server
gaming-agent serve --transport http --password test123

# In Claude Desktop (after connecting), ask:
"Use the demo_terminal_workflow tool to open a terminal, type 'echo hello world', and close it"

这将：

1. ✓ 自动检测您的终端（gnome终端、konsole、xterm、terminal.app、cmd）
2. ✓ 打开一个新的终端窗口
3. ✓ 键入“echo hello world”
4. ✓ 按Enter键执行
5. ✓ 截取屏幕截图进行验证
6. ✓ 使用相应的热键关闭终端

可用工具

总计：24个MCP工具

工作流工具（新增！）

屏幕工具

鼠标工具

键盘工具

使用粘贴功能快速输入文本

这 type_text 工具支架 基于剪贴板的快速粘贴 文本输入速度显著加快的模式：

{
  "tool": "type_text",
  "args": {
    "text": "long command or text here",
    "use_paste": true
  }
}

优点：

• 快10倍 长文本的逐个字符打字
• 理想选择：粘贴长命令、脚本、凭据
• 运作原理：将文本复制到剪贴板，然后使用Ctrl+V（Linux/Windows）或Cmd+V（macOS）进行粘贴
• 默认: use_paste=false （使用逐个字符键入）

何时使用：

• ✓ 大块文本
• ✓ 带有特殊字符的复杂命令
• ✓ 当速度比实时角色可见性更重要时
• ✗ 不支持粘贴输入的游戏
• ✗ 当明确要求逐个字符输入时

文件工具

系统工具

工作流自动化

run_workflow -复合命令执行

使用单个命令按顺序执行多个工具。非常适合复杂的自动化任务。

示例：打开终端并运行命令

{
  "steps": [
    {
      "tool": "execute_command",
      "args": {"command": "gnome-terminal"},
      "wait_ms": 1500,
      "description": "Open terminal"
    },
    {
      "tool": "type_text",
      "args": {"text": "ls -la"},
      "wait_ms": 200,
      "description": "Type command"
    },
    {
      "tool": "press_key",
      "args": {"key": "enter"},
      "wait_ms": 1000,
      "description": "Execute command"
    },
    {
      "tool": "screenshot",
      "args": {},
      "description": "Capture result"
    }
  ]
}

步骤字段：

• tool （必填）：要执行的工具的名称
• args （可选）：传递给工具的参数
• wait_ms （可选）：此步骤后等待毫秒
• description （可选）：人类可读的步骤描述
• continue_on_error （可选）：如果此步骤失败，则继续工作流

退货：

{
  "success": true,
  "total_steps": 4,
  "completed_steps": 4,
  "failed_step": null,
  "results": [...],
  "total_time_ms": 3523,
  "error": null
}

demo_terminal_workflow -现成终端演示

一个方便的工具，在一次通话中展示了完全自动化的能力。

用途：

{
  "text": "echo hello world",
  "terminal_wait_ms": 2000,
  "post_type_wait_ms": 500,
  "post_enter_wait_ms": 1000,
  "capture_screenshot": true,
  "close_terminal": true
}

它的作用：

1. 自动检测平台终端（gnome终端、konsole、xterm、terminal.app、cmd）
2. 打开终端应用程序
3. 等待终端满载
4. 键入提供的命令
5. 按Enter键执行
6. 等待命令输出
7. 捕获屏幕截图以进行验证（可选）
8. 使用适用于平台的热键关闭终端（可选）

退货：

{
  "success": true,
  "terminal_command": "gnome-terminal",
  "platform": "Linux",
  "text_typed": "echo hello world",
  "screenshot": {"success": true, "image": "...", ...},
  "steps_completed": ["detect_terminal", "open_terminal", "wait_for_terminal",
                      "type_text", "press_enter", "capture_screenshot",
                      "close_terminal"],
  "total_time_ms": 4523,
  "error": null
}

平台支持：

• Linux：gnome终端、konsole、xfce4终端、mate终端、tilix、terminal、xterm
• macOS：终端.app
• 视窗：cmd.exe

配置

创建 ~/.gaming-agent/config.json:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8765,
    "password": "your-secure-password"
  },
  "vlm": {
    "enabled": false,
    "provider": "ollama",
    "model": "qwen2.5-vl:3b",
    "endpoint": "http://localhost:11434"
  },
  "security": {
    "allowed_paths": ["/home/user/games", "C:\\Games"],
    "blocked_commands": ["rm -rf", "format", "del /f"],
    "max_command_timeout": 30
  }
}

启用VLM（可选）

要使用 analyze_screen 具有本地视觉模型的工具：

1. 安装Ollama （如果尚未安装）：

   curl -fsSL https://ollama.com/install.sh | sh

1. 拉一个视觉模型:

   ollama pull qwen2.5-vl:3b  # Lightweight, fast
   # or
   ollama pull moondream      # Alternative

1. 安装VLM依赖项:

   pip install ai-gaming-agent[vlm]

1. 在配置中启用 (~/.gaming-agent/config.json):

   {
     "vlm": {
       "enabled": true,
       "provider": "ollama",
       "model": "qwen2.5-vl:3b",
       "endpoint": "http://localhost:11434"
     }
   }

1. 在工作流中使用:

   {
     "tool": "analyze_screen",
     "args": {
       "prompt": "What is the current health percentage?"
     }
   }

部署选项

选项A：克劳德做所有的愿景（最简单）

• Claude分析所有截图
• 游戏PC是简单的执行器
• 游戏PC不需要GPU
• 使用带有承载身份验证的HTTP/SSE传输

选项B：与本地VLM混合（推荐）

• Claude负责高层决策和编排
• 用于快速视觉处理的本地VLM（Qwen2.5-VL，Moondream）
• 速度和智能的最佳平衡
• 降低API成本和延迟

选项C：完全本地（隐私）

• 本地编排器（例如，Ollama的Qwen3-72B）
• 无云API，完全隐私
• 需要强大的硬件（建议使用GPU）
• 使用stdio传输进行本地控制

实际例子

示例1：终端自动化

# Ask Claude: "Run the demo_terminal_workflow with the command 'uname -a'"
# Result: Opens terminal, runs command, captures output, closes

示例2：多步骤工作流

# Ask Claude: "Create a workflow that:
# 1. Opens a file browser
# 2. Navigates to Downloads
# 3. Takes a screenshot
# 4. Closes the window"

# Claude will use run_workflow with execute_command, type_text, screenshot, hotkey

示例3：使用VLM的游戏自动化

# Ask Claude: "Use analyze_screen to check if the game menu is visible,
# then click the 'Start Game' button at coordinates you detect"

# Claude will:
# 1. Call analyze_screen with prompt "Is there a Start Game button? Where?"
# 2. Use VLM response to determine coordinates
# 3. Call click tool with detected coordinates

示例4：批处理文件操作

# Ask Claude: "Create a workflow that backs up all .save files from
# C:\Games\MyGame to C:\Backups\saves-{date}"

# Claude will use run_workflow with list_files, read_file, write_file

安全

• 始终使用强而唯一的密码（至少16个字符，随机）
• 仅在以下情况下限制对游戏目录的文件访问 allowed_paths
• 如果通过互联网访问，请使用VPN（永远不要暴露给公众）
• 为生产启用TLS/HTTPS（使用nginx等反向代理）
• 定期轮换密码（对于高安全环境，每周轮换一次）
• 监视器 ~/.gaming-agent/audit.log 可疑活动
• 设置适当 max_command_timeout 防止失控过程

发展

# Install with uv (recommended)
uv sync --extra dev

# Or with pip
pip install -e ".[dev]"

# Lint
uv run ruff check src tests

# Run unit tests
uv run pytest tests/ --ignore=tests/integration -v

测试

单元测试（CI）

单元测试在每个推送/PR上都在CI中运行。它们测试配置、文件操作和工具界面，而不需要显示。

# Run unit tests only
uv run pytest tests/ --ignore=tests/integration -v

集成测试（仅限本地）

执行集成测试 真正的GUI自动化 并要求：

• 真实显示（X11、Wayland、Windows、macOS）
• tesseract-ocr 用于OCR验证
• pyautogui使用您的显示器

这些测试无法在CI中运行 因为他们需要一个真正的桌面环境。

# Install integration test dependencies
uv sync --extra integration

# Install tesseract (Linux)
sudo apt install tesseract-ocr

# Install tesseract (macOS)
brew install tesseract

# Run integration tests locally
uv run pytest tests/integration -v

集成测试做什么

终端工作流测试

最全面的测试打开一个终端，键入一个命令，并验证输出：

# What the test does:
1. Opens system terminal (gnome-terminal, konsole, xterm, etc.)
2. Types: echo "AGENT_TEST_abc12345"
3. Presses Enter
4. Takes screenshot
5. Runs OCR on screenshot
6. Verifies "AGENT_TEST_abc12345" appears in OCR output
7. Closes terminal with Alt+F4

CI配置

CI仅在使用Python 3.12的GitHub Actions上运行：

# .github/workflows/ci.yml
- Checkout code
- Install uv
- Install Python 3.12
- Install system deps (xvfb, scrot, python3-tk)
- Run ruff lint
- Run unit tests (integration tests excluded)

通过以下方式在CI中自动跳过集成测试 CI=true 环境变量。

许可证

麻省理工学院