sc-bwapi-mcp

Enable AI assistants (e.g., Trae/Claude) to control StarCraft 1 through the BWAPI bridge via MCP (Model Context Protocol).

Architecture

星际1 (1.16.1) ← BWAPI 4.4.0 注入 (Chaoslauncher)
      ↕ 共享内存 + 命名管道
bwapi_bridge.exe (C++, TCP 12345)
      ↕ JSON over TCP
sc-bwapi-mcp (Python MCP server)
      ↕ MCP stdio
Trae / Claude / 任意 MCP 客户端

Related MCP server: defcon-mcp-server

Prerequisites

Installation

1. Install StarCraft 1 + BWAPI

1. Download StarCraft Anthology (free) from the Battle.net client and install it to a path without spaces, e.g., C:\Games\Starcraft

2. Download BWAPI 4.4.0 and install it to a path without spaces, e.g., C:\libraries\BWAPI_440

3. Set the environment variable BWAPI_DIR = C:\libraries\BWAPI_440

4. Copy the contents of StarCraft\ and Windows\ from the BWAPI installation directory into the StarCraft directory

2. Build the BWAPI library (required on first run)

The .lib files for BWAPI 4.4.0 need to be built with VS2022:

$msbuild = "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
$env:BWAPI_DIR = "C:\libraries\BWAPI_440"

# 编译 BWAPILIB + BWAPIClient (Release x86)
& $msbuild "$env:BWAPI_DIR\BWAPILIB\BWAPILIB.vcxproj" /p:Configuration=Release /p:Platform=Win32 /m
& $msbuild "$env:BWAPI_DIR\BWAPIClient\BWAPIClient.vcxproj" /p:Configuration=Release /p:Platform=Win32 /m

# 编译 ExampleAIModule.dll (BWAPI 4.4.0 需要一个 AI 模块才能触发 onStart)
& $msbuild "$env:BWAPI_DIR\ExampleAIModule\ExampleAIModule.vcxproj" /p:Configuration=Release /p:Platform=Win32 /p:OutDir="<星际目录>\bwapi-data\AI\" /m

3. Build the bridge

cd <项目目录>
scripts\build_bridge.bat

Output: cpp\build\Release\bwapi_bridge.exe

4. Configure bwapi.ini

In the StarCraft directory, ensure bwapi-data\bwapi.ini has:

[ai]
ai = bwapi-data/AI/ExampleAIModule.dll
[auto_menu]
auto_menu = OFF

Usage

Startup order (important!)

1. Run Chaoslauncher as administrator → Check "BWAPI Injector 4.4.0 [RELEASE]" → Don't click Start yet

2. Start the bridge: scripts\run_bridge.bat (it waits for the BWAPI server)

3. Click Start in Chaoslauncher → Enter StarCraft → Single Player → Expansion → Play Custom → Choose a map → Start

4. After entering the game screen, the bridge automatically connects and pushes status

Configure MCP client

Add the following to Trae's MCP configuration:

{
  "mcpServers": {
    "sc-bwapi": {
      "command": "C:\\Users\\<你>\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "<项目路径>", "sc-bwapi-mcp"]
    }
  }
}

Restart Trae, and you can call the tools.

MCP tools

Troubleshooting

• Bridge stuck at "Game table mapping not found": StarCraft is not launched; it is waiting normally.

• Bridge cannot connect to the pipe: Exit the game and re-enter (the previous bridge was force-killed, and BWAPI's connected flag is stuck).

• build failed: The bridge uses getBuildLocation to find a location automatically; make sure there is empty space within the creep range.

• 0 FPS: The computer configuration is insufficient; switch to 1v1 and press F5 in game to reduce speed.