🚀 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和功能需求。