🎮 Xbox AI Controller

Control your Xbox One & Xbox Series console directly from AI Agents (Antigravity, Claude, Cursor) or CLI using natural language.

Launch games (FC 25, Minecraft, Halo, etc.), send controller button presses, manage media playback, adjust TV volume via HDMI-CEC, and power on/off over Wi-Fi and official Microsoft Cloud APIs.

⚡ Architecture: The Dual-Layer Engine

xbox-ai-controller combines two complementary communication protocols to give your AI agent complete command over your console:

flowchart TD
    Agent["🤖 AI Agent (Antigravity / Claude / Cursor)"] --> MCP["⚡ Xbox AI Controller MCP Server"]
    CLI["💻 CLI Terminal (`npx xbox-ai`)"] --> MCP

    subgraph Dual_Engine ["Dual-Layer Control Engine"]
        MCP -->|Local UDP 5050| SG["📡 Local SmartGlass Engine"]
        MCP -->|HTTPS OAuth| XCCS["☁️ Microsoft XCCS Cloud API"]
    end

    SG -->|Magic Wake Packets| XboxPower["Power On (Remote Wake)"]
    SG -->|Gamepad Inputs| XboxInput["Buttons (A, B, X, Y, Guide, D-Pad)"]
    SG -->|Media & TV Remote| XboxMedia["Play, Pause, TV Volume (HDMI-CEC)"]

    XCCS -->|Official UWA Protocol| XboxLaunch["1-Click Game & App Launcher"]
    XCCS -->|Title Hub| XboxTitles["Enumerate Installed Games"]
    XCCS -->|Power Commands| XboxOff["Standby / Cloud Power-Off"]

    XboxPower --> Console["🎮 Xbox One / Xbox Series X|S"]
    XboxInput --> Console
    XboxMedia --> Console
    XboxLaunch --> Console
    XboxTitles --> Console
    XboxOff --> Console

1. Local SmartGlass Engine (UDP Port 5050):

   • Direct, zero-latency local network communication.

   • Remote Wake-up magic packets (0xdd02).

   • Controller button presses (A, B, X, Y, D-Pad, Nexus / Guide Menu, Menu, View).

   • Media playback control (Play, Pause, Stop, Next, Previous, Rewind, Fast-Forward).

   • TV / soundbar volume control via console HDMI-CEC (Volume Up, Volume Down, Mute).

2. Microsoft Console Command Service (XCCS Cloud):

   • Official Microsoft UWA protocol (xccs.xboxlive.com).

   • 1-Click Game Launching: Bypasses manual on-screen navigation to boot any game or app directly by name (e.g., "Open FC 25", "Launch Minecraft", "Open YouTube").

   • Safe 2FA Authentication: Uses Microsoft's official device-code flow (microsoft.com/link) — no passwords needed.

Related MCP server: samsung-tv-mcp

✨ Features

• 🎯 1-Click Game Launcher: Launch installed titles (EA Sports FC 25, Minecraft, Cricket 24, Halo Infinite, Asphalt Legends, War Thunder, Netflix, Spotify, etc.) by name.

• ⚡ Zero-Lag Gamepad Navigation: Navigate menus and dashboards using virtual controller inputs.

• 📺 Media & TV Volume Remote: Play/pause streaming apps and adjust TV volume through HDMI-CEC.

• 🔌 Power Management: Wake the console from Sleep mode or put it into standby remotely.

• 🔐 2FA-Friendly Device-Code Auth: Authenticate using official microsoft.com/link codes without exposing your password in chat.

• 🤖 Universal MCP Support: Plugs into Google Deepmind's Antigravity CLI (agy), Claude Desktop, Cursor, Windsurf, or custom LLM frameworks.

• 💻 Standalone CLI Included: Every feature can be run directly from terminal (npx xbox-ai) without an AI agent.

🚀 Quickstart

1. Installation

Clone and install dependencies:

git clone https://github.com/SherrySoft/xbox-ai-controller.git
cd xbox-ai-controller
npm install

2. Configure Your Xbox Console (One-Time)

On your Xbox One or Xbox Series console:

1. Enable Sleep Mode:

   • Go to Settings > General > Power options and select Sleep (Instant-On).

2. Enable Remote Features:

   • Go to Settings > Devices & connections > Remote features and check Enable remote features.

   • Under Xbox app preferences, select Allow connections from any device.

3. Discover Your Console

Run the discovery tool on the same Wi-Fi/LAN:

node bin/cli.js discover

It will detect your Xbox's IP address, name, and Live Device ID, and save them automatically to ~/.xbox-mcp/config.json.

4. Authenticate for 1-Click Game Launching

To allow your AI agent to launch games directly without manual on-screen navigation:

node bin/cli.js login

1. Open the URL displayed on your screen: 👉 https://www.microsoft.com/link

2. Enter the short code displayed in the terminal.

3. Approve with your Xbox account. Tokens are securely stored locally on your machine.

🤖 AI Agent Integration (MCP Setup)

⚡ 1-Click Auto Installer (Recommended)

No need to manually find or edit JSON files! Simply run:

npx github:SherrySoft/xbox-ai-controller install

(Or npx xbox-ai-controller install if installed via npm)

The interactive installer will ask:

1. Which AI Agent you want to configure (Antigravity, Claude Desktop, Cursor, Windsurf, or All).

2. Which runner you prefer (npx zero-install or local path).

It detects your operating system, locates your config file, and safely injects the MCP server entry automatically!

Manual Configuration (Optional)

If you prefer to configure manually, add the following to your agent's config file:

Antigravity CLI (agy) — ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "xbox": {
      "command": "npx",
      "args": ["-y", "xbox-ai-controller"]
    }
  }
}

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "xbox": {
      "command": "npx",
      "args": ["-y", "xbox-ai-controller"]
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "xbox": {
      "command": "npx",
      "args": ["-y", "xbox-ai-controller"]
    }
  }
}

(Note: You can also replace "npx", ["-y", "xbox-ai-controller"] with "node", ["/path/to/xbox-ai-controller/src/server.js"] if running from a local clone).

---

## 💬 Natural Language Prompts

Once configured, simply talk to your AI agent naturally:

- *"Turn on my Xbox"*
- *"Launch EA Sports FC 25"*
- *"Open Minecraft"*
- *"Open YouTube"*
- *"Go back to the Home screen"*
- *"Press the Xbox Guide button"*
- *"Press Down and select A"*
- *"Pause the video"*
- *"Turn the TV volume up"*
- *"Record that game clip"*
- *"Put my Xbox to sleep"*

---

## 🛠️ CLI Usage Guide

You can also use the controller directly from your terminal:

```bash
# Scan local network for consoles
node bin/cli.js discover

# Power on / wake
node bin/cli.js wake

# Launch games & apps
node bin/cli.js launch "FC 25"
node bin/cli.js launch "Minecraft"
node bin/cli.js launch "YouTube"
node bin/cli.js launch "Home"

# List installed games on console
node bin/cli.js apps

# Controller button navigation
node bin/cli.js button nexus    # Open Guide menu
node bin/cli.js button a        # Select (A)
node bin/cli.js button b        # Back (B)
node bin/cli.js button down     # D-Pad Down

# Media & Volume
node bin/cli.js media playpause
node bin/cli.js volume up
node bin/cli.js volume down

# Power off
node bin/cli.js off

🎮 Available MCP Tools

🔒 Security & Privacy

• No Passwords Stored: Authentication uses official Microsoft OAuth Device-Code flow. Passwords are never handled or logged.

• Local Storage: All tokens, configuration, and IP addresses remain strictly on your local PC in ~/.xbox-mcp/ and are excluded in .gitignore.

• First-Party Microsoft APIs: Cloud commands communicate exclusively with https://xccs.xboxlive.com using standard TLS encryption.

📄 License

This project is licensed under the MIT License.