# sc2-mcp — StarCraft II AI Coach for ChatGPT, Claude, Codex and other MCP clients

An [MCP](https://modelcontextprotocol.io) server for [StarCraft2.ai](https://www.starcraft2.ai). From ChatGPT, Claude, Claude Code, Codex, Cursor or any other MCP client you can:

- **Ask StarCraft II questions.** Answers come from the same knowledge base the AI Coach cites: Liquipedia unit data, current patch notes, strategy articles and pro-game insights.
- **Upload a replay** from a file on your computer or from a download link.
- **Get an AI Coach report** on a game: strengths, mistakes, key moments and what to work on.
- **Ask follow-up questions** about a game ("why did I lose that fight at 8:30?").

Uploading works without an account. Everything else needs a StarCraft2.ai account. To upload every game automatically instead, install the [auto-uploader](https://www.starcraft2.ai/en/uploader). The tools use your account's **minerals**, at the same prices as the website:

| What | Cost |
|---|---|
| Knowledge search, uploads, reading an existing report | free |
| AI Coach report on a replay | 1 mineral (free if the replay already has one) |
| Follow-up questions on a replay | first 3 free, then 1 mineral per 20 |
| Check-in note across your recent games | reading the saved one is free; a new one is 1 mineral |

**A new connection can't spend minerals at all until you allow it** on [starcraft2.ai/auth/mcp](https://www.starcraft2.ai/auth/mcp) under Connected apps, so a sign-in someone tricked you into approving can read but not spend. Once allowed, a tool still never spends unless it's called with `confirm_spend: true`, and the tool descriptions tell the assistant to ask you first. If your client supports MCP elicitation, the server also asks you directly before spending, so nothing the assistant reads in a replay or a report can approve a purchase for you. Buy minerals at [starcraft2.ai/en/billing](https://www.starcraft2.ai/en/billing).

## Install

### ChatGPT and Claude (hosted connector, nothing to install)

Add a custom connector with this URL:

```
https://www.starcraft2.ai/api/mcp
```

- **Claude** (claude.ai, desktop and mobile apps): **Customize → Connectors → Add custom connector**, then **Connect** and sign in. Team and Enterprise owners add it under Organization settings → Connectors.
- **ChatGPT** (paid plans, chatgpt.com): turn on developer mode (**Settings → Security and login → Developer mode**), then **Plugins → +**, paste the URL and sign in. ChatGPT can pass an attached replay file straight to `upload_replay`.

The hosted connector runs the same tools as this package on starcraft2.ai (it imports `sc2-mcp/lib`). It signs in with OAuth and has no `login`/`logout` tools; spending still needs to be allowed under Connected apps. Step-by-step with screenshots: [starcraft2.ai/en/mcp](https://www.starcraft2.ai/en/mcp).

### Claude Code (plugin)

```
/plugin marketplace add tomkit/sc2-mcp
/plugin install sc2-coach@starcraft2-ai
```

The plugin adds the MCP server and a skill that tells Claude how to use it. Then ask something like *"analyze my latest SC2 replay"* and Claude will sign you in.

### Codex (plugin)

```
codex plugin marketplace add tomkit/sc2-mcp
codex plugin add sc2-coach@starcraft2-ai
```

Same server and skill as the Claude Code plugin. Start a new Codex session and ask it to analyze a replay; it will sign you in through the browser. `codex mcp list` should show `sc2`.

Or register just the server: `codex mcp add sc2 -- node /absolute/path/to/sc2-mcp/dist/index.js`.

### Claude Code (server only)

```
git clone https://github.com/tomkit/sc2-mcp ~/sc2-mcp
claude mcp add sc2 -- node ~/sc2-mcp/dist/index.js
```

### Claude Desktop, Cursor and other clients

Nothing to download: the config runs the server straight from this repo with `npx`. In Claude Desktop, open **Claude → Settings… → Developer → Edit Config**, replace the contents of `claude_desktop_config.json` with this (or add the `sc2` entry to your existing `mcpServers`), save, and quit and reopen Claude:

```json
{
  "mcpServers": {
    "sc2": {
      "command": "npx",
      "args": ["-y", "github:tomkit/sc2-mcp"]
    }
  }
}
```

Then check **+ → Connectors → Manage connectors** lists `sc2`, and ask Claude to sign you in to StarCraft2.ai. Step-by-step instructions with screenshots: [starcraft2.ai/en/mcp](https://www.starcraft2.ai/en/mcp#other). A local clone works too: `"command": "node", "args": ["/absolute/path/to/sc2-mcp/dist/index.js"]`.

Claude Desktop can also use the hosted connector above, which needs no Node.js and no config file.

It needs Node.js 18.17 or newer on your `PATH`, including for the Claude Code and Codex plugins (neither installer brings Node with it). `dist/index.js` is a self-contained bundle, so there is nothing to `npm install`.

## Signing in

Every tool except `login` needs you signed in. `login` gives you two ways to approve, and whichever you finish first signs you in:

- **On the same computer:** if you ask for it (the assistant passes `open_browser`), it opens StarCraft2.ai in your browser. Sign in if you aren't already, check the request and click **Allow**. That's the OAuth 2.1 authorization-code flow with PKCE and a loopback redirect to `127.0.0.1` ([RFC 8252](https://www.rfc-editor.org/rfc/rfc8252)).
- **From your phone or any other device:** it also gives you a short code like `BCDF-GHJK`. Open [starcraft2.ai/auth/device](https://www.starcraft2.ai/auth/device), enter the code and approve. That's the device authorization grant ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)): nothing is redirected to your computer, so it works when the server runs on a Mac you're not sitting at, over SSH, or in a container. Only enter a code that your own assistant gave you, and never one someone sent you.

The server never sees your password. The resulting token is saved to `~/.config/sc2-mcp/credentials.json` (`%APPDATA%\sc2-mcp` on Windows) with owner-only permissions. It lasts 180 days for a browser sign-in and 30 days for a code sign-in, and you get an email each time an app connects. `logout` revokes it, and so does **Disconnect** on [starcraft2.ai/auth/mcp](https://www.starcraft2.ai/auth/mcp), which lists every connected device.

You can also set `SC2_API_TOKEN` in the server's environment; it takes precedence over the saved token, which follows the MCP spec's advice for stdio servers to take credentials from the environment. Treat a token like a password: it can spend your minerals.

## Tools

| Tool | What it does |
|---|---|
| `login` / `logout` | Browser sign-in; revoke and forget the token |
| `get_account` | Mineral balance, claimed SC2 profile, prices |
| `search_sc2_knowledge` | Passages from the SC2 knowledge base for general questions |
| `upload_replay` | Upload a `.SC2Replay` (or Brood War `.rep`) by `path` or `url`. Works without signing in (anonymous upload) |
| `list_my_replays` | Your games, newest first: ones you played (via your linked SC2 profile), coached, asked about or uploaded, with your result and whether a report exists |
| `search_replays` | Search your games (or another player's, by name) by date range, map, opponent, teammates, units built (e.g. at least 8 Liberators and Vikings), your race, opponent's race, win/loss, 1v1/2v2 and whether a report exists. Each result has its link |
| `get_analysis` | A replay's details and its AI Coach report, if one exists |
| `analyze_replay` | Run the AI Coach on one side of a game (1 mineral, needs `confirm_spend`; `player` picks the side, default yours) |
| `ask_about_replay` | Ask the coach a follow-up question about a coached replay |
| `unlock_more_questions` | 20 more follow-up questions on a replay (1 mineral, needs `confirm_spend`) |
| `coach_my_progress` | The coach's check-in note across your last 5 coached ranked (or unranked) games: are you fixing what it flagged last time, what's working, the one recurring leak, and what to work on next, citing the games. The saved note is free; a new one is 1 mineral (`refresh` + `confirm_spend`) |

A coach run takes 3–7 minutes. `analyze_replay` waits up to `wait_seconds` (default 50) and sends MCP progress notifications while it waits. If the run isn't done by then it returns and the run carries on; `get_analysis` picks up the report. Runs that fail on the site's side are refunded automatically.

## Configuration

| Variable | Default | |
|---|---|---|
| `SC2_API_TOKEN` | – | Use this token instead of the browser sign-in |
| `SC2_API_BASE` | `https://www.starcraft2.ai` | Site origin (for local development) |
| `SC2_MCP_CREDENTIALS` | `~/.config/sc2-mcp/credentials.json` | Where the token is saved |
| `SC2_MCP_NO_BROWSER` | – | `1` to print the sign-in URL instead of opening a browser |

## Development

```
npm install
npm run build   # typecheck + bundle to dist/index.js (commit the bundle)
npm test        # protocol and credit-gating tests against a mock site
npm run inspect # MCP Inspector
```

The end-to-end test (real browser sign-in, upload, a paid coach run and follow-ups against a local build of the site) lives in the site's repository.

## License

MIT