# xbox-mcp

An MCP server that knows what you (or any Xbox player) are playing right now and
what you've been up to lately. Backed by the unofficial [OpenXBL](https://xbl.io)
Xbox Live API.

## Tools

| Tool | What it does | Other players? |
|------|--------------|----------------|
| `get_current_game` | Online state, device, and the game running right now with rich-presence detail | Yes (gamertag/xuid) |
| `get_recent_games` | Recently played games, newest first, with last-played date, devices, and per-title achievement/gamerscore progress | Yes |
| `get_activity` | Your screenshots, game clips, and achievement posts, newest first | Self only* |
| `get_profile` | Gamertag, gamerscore, account tier, reputation, bio, location | Yes |
| `search_players` | Find players by gamertag; returns their XUID for follow-up lookups | Yes |

Every player-facing tool takes an optional `gamertag` (or `xuid`). Omit both to
target your own account. Pass a `gamertag` and the server resolves it to an XUID
via `/search` (cached), then queries that player.

\* The OpenXBL activity feed is only exposed for the authenticated account.

## Configuration

One environment variable:

- `OPENXBL_API_KEY` — your OpenXBL API key from <https://xbl.io> (sign in with your
  Microsoft/Xbox account, then copy the key from the dashboard).

The key never leaves the server; MCP clients only ever see tool results.

## Run locally

```bash
npm install
npm run build
OPENXBL_API_KEY=xxxx node dist/index.js   # speaks MCP over stdio
```

Or for development without a build step:

```bash
OPENXBL_API_KEY=xxxx npm run dev
```

## Notes

- The OpenXBL free tier allows ~150 requests/hour. Each tool call is 1-2 requests
  (gamertag lookups add one). Bursty history sweeps can hit the limit.
- Minutes-played and the cross-title recent-achievement feed are not reliably
  exposed by the API, so they are intentionally omitted. Per-title achievement
  *progress* is surfaced through `get_recent_games` instead.