金大哥 - controller_mcp MCP 详情

article

README

🚀 Xbox控制器MCP服务器

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

✨ 主要特性

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

📦 安装指南

使用uv（推荐）

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

uv sync

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

替代方案：使用pip

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

pip install -r requirements.txt

硬件模式（可选）

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

安装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：用于数据验证。

添加新功能

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

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

开发环境设置

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

uv sync --dev

启动服务器：

uv run main.py

测试

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

📄 许可证

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

贡献

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

controller_mcp