Controller MCP

🚀 Xbox控制器MCP服务器

本项目是一个MCP（模型上下文协议）服务器，借助FastMCP和vgamepad实现了Xbox控制器的模拟功能。通过该服务器，你可以方便地模拟Xbox控制器的各种操作，为开发和测试提供便利。

✨ 主要特性

• 按键控制：可对任意Xbox控制器按键进行按下、释放或点击操作。
• 模拟摇杆：能够控制左右模拟摇杆的位置。
• 扳机控制：可设置左右扳机的值。
• 状态管理：获取当前控制器的状态，并将其重置为中立状态。
• 模拟模式：无需硬件驱动即可运行，适用于测试和开发场景。
• 硬件模式：借助ViGEmBus驱动，提供完整的虚拟控制器支持。
• 跨平台支持：主要在Windows系统上运行，同时具备潜在的Linux支持能力。

📦 安装指南

使用uv（推荐）

1. 克隆或下载本仓库。
2. 使用uv安装依赖：

uv sync

此命令将创建一个虚拟环境，并从pyproject.toml文件中安装所有依赖项。

替代方案：使用pip

如果你更喜欢使用pip，可以执行以下命令：

pip install -r requirements.txt

硬件模式（可选）

若要启用实际的控制器输入（而非模拟模式），请按以下步骤操作：

1. 安装ViGEmBus驱动：
   • 从以下链接下载：https://github.com/ViGEm/ViGEmBus/releases
   • 以管理员身份运行ViGEmBus_Setup_x64.exe。
   • 重启系统。

若未安装ViGEmBus驱动，服务器将以模拟模式运行，此时仅跟踪控制器状态，不会向系统发送实际输入。

💻 使用示例

启动MCP服务器

使用uv启动：

uv run main.py

或者直接使用Python启动：

python main.py

服务器启动后将监听MCP连接，并自动检测是使用硬件模式（需安装ViGEmBus）还是模拟模式。

可用工具

按键控制

• press_button(button)：按下指定的控制器按键。
• release_button(button)：释放指定的控制器按键。
• tap_button(button, duration=0.1)：点击指定按键（按下并释放）。

模拟控制

• set_left_stick(x, y)：设置左摇杆的位置（取值范围为 -1.0 到 1.0）。
• set_right_stick(x, y)：设置右摇杆的位置（取值范围为 -1.0 到 1.0）。
• set_triggers(left, right)：设置扳机的值（取值范围为 0.0 到 1.0）。

状态管理

• reset_controller()：将控制器重置为中立状态。
• get_controller_state()：获取当前控制器的状态。
• list_available_buttons()：列出所有可用的按键名称。
• get_system_info()：获取系统信息和设置状态。

可用按键

• 面键：A、B、X、Y
• 肩键：LB、RB
• 菜单键：BACK、START
• 摇杆按键：LS、RS
• 方向键：DPAD_UP、DPAD_DOWN、DPAD_LEFT、DPAD_RIGHT

MCP客户端使用示例

# 按下A键
await client.call_tool("press_button", {"button": "A"})

# 将左摇杆移动到右上方
await client.call_tool("set_left_stick", {"x": 0.5, "y": 0.5})

# 将两个扳机都设置为半按状态
await client.call_tool("set_triggers", {"left": 0.5, "right": 0.5})

# 点击X键0.2秒
await client.call_tool("tap_button", {"button": "X", "duration": 0.2})

# 重置所有设置
await client.call_tool("reset_controller", {})

📚 详细文档

架构

• FastMCP：提供MCP服务器框架。
• vgamepad：负责虚拟Xbox控制器的创建和输入注入。
• Pydantic：用于数据验证和序列化。
• 双模式操作：
  • 硬件模式：借助ViGEmBus驱动提供完整的虚拟控制器功能。
  • 模拟模式：仅跟踪状态，不发送实际输入（备用模式）。

坐标系

模拟摇杆

• 取值范围：X轴和Y轴的取值范围均为 -1.0 到 1.0。
• X轴：-1.0 表示左，1.0 表示右。
• Y轴：-1.0 表示下，1.0 表示上。

扳机

• 取值范围：0.0 表示未按下，1.0 表示完全按下。

项目文件

• main.py：实现了带有Xbox控制器模拟功能的主MCP服务器。
• pyproject.toml：项目配置和依赖文件（兼容uv/pip）。
• requirements.txt：供pip用户使用的Python依赖文件。
• uv.lock：用于精确锁定依赖版本的锁文件（uv）。
• mcp-config.json：MCP客户端配置文件。
• README.md：本项目文档。

MCP客户端配置

若要将此服务器与Claude Desktop或其他MCP客户端配合使用，请将mcp-config.json中的配置添加到你的MCP客户端设置中：

{
  "mcpServers": {
    "xbox-controller": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "c:\\Users\\blain\\Documents\\git\\controller_mcp",
      "env": {},
      "description": "Xbox Controller Emulator MCP Server - Provides tools to emulate Xbox controller inputs including buttons, analog sticks, and triggers. Supports both hardware mode (with ViGEmBus) and simulation mode."
    }
  }
}

使用uv配置

如果你使用的是uv，也可以将其配置为使用uv执行：

{
  "mcpServers": {
    "xbox-controller": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "c:\\Users\\blain\\Documents\\git\\controller_mcp",
      "env": {},
      "description": "Xbox Controller Emulator MCP Server - Provides tools to emulate Xbox controller inputs including buttons, analog sticks, and triggers. Supports both hardware mode (with ViGEmBus) and simulation mode."
    }
  }
}

🔧 技术细节

故障排除

硬件模式与模拟模式

服务器会自动检测ViGEmBus驱动是否可用：

• 硬件模式：虚拟控制器输入将发送到系统。
• 模拟模式：仅跟踪控制器状态，不发送实际输入。

启动服务器时，可查看控制台输出以确定当前使用的模式。

Windows系统

• 确保你具备创建虚拟设备的必要权限。
• 某些杀毒软件可能会阻止虚拟设备的创建。
• 首次运行可能需要管理员权限。
• 若ViGEmBus安装失败，服务器仍可在模拟模式下运行。

游戏应用

• 大多数游戏应能自动检测到虚拟控制器（仅适用于硬件模式）。
• 你可以在Windows的“游戏控制器”设置中验证控制器是否正常工作。
• 某些游戏可能要求虚拟控制器是唯一连接的控制器。
• 在模拟模式下，不会向游戏发送实际的控制器输入。

开发与测试

• 使用模拟模式进行测试和开发，不会影响其他应用程序。
• 使用get_system_info()工具检查当前模式和设置状态。
• 所有MCP工具在两种模式下均可使用，仅实际输入注入方式有所不同。

开发

项目结构

本项目采用现代Python工具：

• uv：用于快速管理依赖和创建虚拟环境。
• pyproject.toml：项目配置文件。
• FastMCP：实现MCP服务器。
• Pydantic：用于数据验证。

添加新功能

服务器采用模块化设计。若要添加新功能，请按以下步骤操作：

1. 在main.py中的XboxControllerEmulator类中添加新方法。
2. 使用@mcp.tool()装饰器创建相应的MCP工具。
3. 更新文档。
4. 在硬件和模拟模式下进行测试。

开发环境设置

1. 克隆仓库。
2. 安装开发依赖：

uv sync --dev

3. 启动服务器：

uv run main.py

测试

• 服务器在硬件和模拟模式下均提供全面的日志记录。
• 通过启动服务器并连接MCP客户端来测试单个功能。
• 使用get_system_info()工具验证设置。
• 所有功能均可在模拟模式下进行测试，无需依赖硬件。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

贡献

欢迎贡献代码！请随时提交拉取请求或提出问题，反馈Bug和功能需求。