Wow Casc Server

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

Tools

Tool	Description
casc_open	Open CASC storage, returns handleId + buildNumber
casc_find	Find files by wildcard mask (JS pre-filter, optional branch/readability filters)
casc_read	Read file content (text or base64)
casc_close	Close storage handle

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.

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.

Field	Description
method	"js-pre-filter" — confirms JS path
_source	"listfile" — data from CSV, not CASC index
size	null — use casc_read for file details
available	null — use casc_read for file details

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:

Field	Description
available	true when the active CASC handle can read the candidate
size	byte size when readable, otherwise null
verification	"readable" or "unreadable"
verifyError	error text for unreadable candidates

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

Operation	Timeout
casc_open	30s
casc_find	60s
casc_read	30s
Listfile download	30s

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.