Xbox Controller MCP Server

Xbox Controller MCP Server

An MCP (Model Context Protocol) server that provides Xbox controller emulation capabilities using FastMCP and vgamepad.

Features

• Button Control: Press, release, or tap any Xbox controller button
• Analog Sticks: Control left and right analog stick positions
• Triggers: Set left and right trigger values
• State Management: Get current controller state and reset to neutral
• Simulation Mode: Runs without hardware drivers for testing and development
• Hardware Mode: Full virtual controller support with ViGEmBus driver
• Cross-platform: Works on Windows (primary), with potential Linux support

Prerequisites

• Python 3.12 or higher
• uv package manager
• Windows OS (recommended for best vgamepad support)

Installation

Using uv (Recommended)

1. Clone or download this repository
2. Install dependencies using uv:

This will create a virtual environment and install all dependencies from pyproject.toml.

Alternative: Using pip

If you prefer to use pip:

For Hardware Mode (Optional)

To enable actual controller input (instead of simulation mode):

1. Install ViGEmBus driver:
   • Download from: https://github.com/ViGEm/ViGEmBus/releases
   • Run ViGEmBus_Setup_x64.exe as Administrator
   • Reboot your system

Without the ViGEmBus driver, the server runs in simulation mode where controller state is tracked but no actual input is sent to the system.

Usage

Running the MCP Server

With uv:

Or with Python directly:

The server will start and listen for MCP connections. It automatically detects whether to run in hardware mode (with ViGEmBus) or simulation mode.

Available Tools

Button Controls

• press_button(button): Press a controller button
• release_button(button): Release a controller button
• tap_button(button, duration=0.1): Tap a button (press and release)

Analog Controls

• set_left_stick(x, y): Set left stick position (-1.0 to 1.0)
• set_right_stick(x, y): Set right stick position (-1.0 to 1.0)
• set_triggers(left, right): Set trigger values (0.0 to 1.0)

State Management

• reset_controller(): Reset controller to neutral state
• get_controller_state(): Get current controller state
• list_available_buttons(): List all available button names
• get_system_info(): Get system information and setup status

Available Buttons

• Face Buttons: A, B, X, Y
• Shoulder Buttons: LB, RB
• Menu Buttons: BACK, START
• Stick Clicks: LS, RS
• D-Pad: DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT

Example Usage with MCP Client

Architecture

• FastMCP: Provides the MCP server framework
• vgamepad: Handles virtual Xbox controller creation and input injection
• Pydantic: Data validation and serialization
• Dual Mode Operation:
  • Hardware Mode: Full virtual controller with ViGEmBus driver
  • Simulation Mode: State tracking without actual input (fallback mode)

Coordinate Systems

Analog Sticks

• Range: -1.0 to 1.0 for both X and Y axes
• X-axis: -1.0 (left) to 1.0 (right)
• Y-axis: -1.0 (down) to 1.0 (up)

Triggers

• Range: 0.0 (not pressed) to 1.0 (fully pressed)

Project Files

• main.py: Main MCP server implementation with Xbox controller emulation
• pyproject.toml: Project configuration and dependencies (uv/pip compatible)
• requirements.txt: Python dependencies for pip users
• uv.lock: Lockfile for exact dependency versions (uv)
• mcp-config.json: MCP client configuration file
• README.md: This documentation

Configuration for MCP Clients

To use this server with Claude Desktop or other MCP clients, add the configuration from mcp-config.json to your MCP client settings:

Using with uv

If you're using uv, you can also configure it to use uv for execution:

Troubleshooting

Hardware vs Simulation Mode

The server automatically detects whether the ViGEmBus driver is available:

• Hardware Mode: Virtual controller inputs are sent to the system
• Simulation Mode: Controller state is tracked but no actual input is sent

Check the console output when starting the server to see which mode is active.

Windows

• Ensure you have the necessary permissions to create virtual devices
• Some antivirus software may block virtual device creation
• The first run might require administrator privileges
• If ViGEmBus installation fails, the server will still work in simulation mode

Gaming Applications

• Most games should detect the virtual controller automatically (hardware mode only)
• You can verify the controller is working in Windows' "Game Controllers" settings
• Some games may require the virtual controller to be the only controller connected
• In simulation mode, no actual controller input is sent to games

Development and Testing

• Use simulation mode for testing and development without affecting other applications
• Use the get_system_info() tool to check the current mode and setup status
• All MCP tools work in both modes - only the actual input injection differs

Development

Project Structure

The project uses modern Python tooling:

• uv for fast dependency management and virtual environments
• pyproject.toml for project configuration
• FastMCP for MCP server implementation
• Pydantic for data validation

Adding New Features

The server is built modularly. To add new functionality:

1. Add methods to the XboxControllerEmulator class in main.py
2. Create corresponding MCP tools using the @mcp.tool() decorator
3. Update the documentation
4. Test in both hardware and simulation modes

Development Setup

1. Clone the repository
2. Install development dependencies:
   uv sync --dev
3. Run the server:
   uv run main.py

Testing

• The server includes comprehensive logging for both hardware and simulation modes
• Test individual functions by running the server and connecting with an MCP client
• Use the get_system_info() tool to verify the setup
• All functionality works in simulation mode for testing without hardware dependencies

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.