wow-casc-mcp-server

MCP server for reading World of Warcraft client files via CASC storage.

Tools

Use the WoW root Data directory for casc_open, for example D:\Program Files\World of Warcraft\Data. Do not use _retail_\Data; the _retail_ directory is the live client/addon folder, not the CASC storage root.

Related MCP server: wow-mcp

casc_find — JS Pre-Filter

v1.3.0 replaced native CascFindFirstFile/CascFindNextFile iteration with JS readline streaming. The community listfile (2.1M entries, 139MB) is filtered line-by-line via regex in ~2-5 seconds. Native iteration previously took 3+ minutes.

Mask matching: case-insensitive, * matches any characters, ? matches single character.

Performance: < 5s for full 2.1M entry scan. 60s timeout as safety net.

casc_find is discovery by default. A listfile match is only a candidate and may not be readable in the active client build.

Branch / Flavor Filtering

Pass one of branch, environment, flavor, productFlavor, or clientFlavor to reduce cross-version candidates. Supported values include: retail/mainline, ptr, classic, vanilla, tbc, wrath, cata, and mists.

Filtering is conservative: paths with explicit mismatched branch segments are skipped, while generic/shared paths remain included.

Example Retail/mainline search:

{
  "mask": "interface/addons/blizzard_uiparent/mainline/*.lua",
  "branch": "retail",
  "maxResults": 20
}

Readability Verification

Set verify: true to attempt an open/read check for each returned candidate. Returned files are annotated with:

Verification is applied only to returned candidates, not to every matching listfile row. For API/source cache provenance, use casc_read on the exact readable path and record the buildNumber.

Example:

{
  "mask": "interface/addons/blizzard_uiparent/mainline/uiparent.lua",
  "branch": "mainline",
  "verify": true,
  "maxResults": 5
}

casc_open — Build Detection

casc_open response includes buildNumber (Blizzard's internal build counter). Compare against last known value to detect client changes and invalidate cached CASC data.

Current Retail UI source is commonly under paths such as interface/addons/blizzard_*/mainline/* or interface/addons/blizzard_*/shared/*. Older Interface/FrameXML/*.lua listfile hits can be stale for the current build; treat them as candidates until casc_read succeeds.

Timeouts

Setup

npm install

Community Listfile

casc_find auto-downloads the latest community listfile on first use — no manual setup needed.

Source: wowdev/wow-listfile — the canonical community listfile, same source used by wow.tools.local.

How it works:

• First casc_find without listfilePath → downloads community-listfile.csv to server directory

• Subsequent calls → uses local cache

• Cache older than 1 day → auto re-downloads

• Failed download → falls back to stale cache (if exists), otherwise casc_find reports that no listfile is available

Manual override: Pass listfilePath in casc_find to use a custom listfile instead.

Format: CSV with FileDataID;filename lines:

1;interface/cinematics/logo_800.avi
53183;sound/music/citymusic/darnassus/darnassus intro.mp3

MCP Config

{
  "mcpServers": {
    "wow-casc": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/mcp-casc/index.js"]
    }
  }
}

Requirements

• Node.js 18+

• World of Warcraft installation (retail)

• @jamiephan/casclib and @modelcontextprotocol/sdk (installed via npm)

Version

1.3.0 — JS pre-filter casc_find (2-5s vs 3min), 60s timeout, buildNumber in casc_open response, optional branch filtering and readable-candidate verification.