wowaudit-mcp-server

MCP server for the documented WoWAudit API. It exposes guild roster, raid planning, attendance, weekly activity, wishlists, loot history, and applications as structured tools for Raid Lens and other MCP clients.

The server uses stdio and @modelcontextprotocol/server 2.x. It serves the current MCP protocol and retains the SDK's legacy 2025-era initialize handshake for older clients. Every result includes native structuredContent plus the same JSON as a text block for clients that do not consume structured results.

Requirements

• Node.js 20 or newer.
• A WoWAudit team API key. A team administrator can copy it from the team's Settings > Team > API key field, or open https://wowaudit.com/api and select the team. WoWAudit does not currently expose a scoped read-only Public API key; this server enforces read-only access locally by default.

Setup

npm install

Create .env from .env.example, then set:

WOWAUDIT_API_KEY=your-team-api-key

Build the server:

npm run build

The API key is loaded lazily, so the MCP process can start and list tools without a configured key. API calls return a structured configuration error until the key is available.

MCP client configuration

Use the compiled entry point from an MCP client:

{
  "mcpServers": {
    "wowaudit": {
      "command": "node",
      "args": [
        "C:\\programming\\typescript\\wowaudit-mcp-server\\dist\\index.js"
      ]
    }
  }
}

The server resolves .env relative to its installed location, not the MCP client's working directory. Credentials may instead be supplied through the client's env configuration.

Integrators that must preserve the API key's exact UTF-8 bytes can pass it through a dedicated inherited file descriptor instead of an environment variable. Inherit a readable descriptor as FD 3 and set only WOWAUDIT_API_KEY_FD=3. The descriptor contents must be non-empty valid UTF-8 and are read once, cached in memory for the MCP process lifetime, and reused without trimming or newline removal. Do not also set a non-empty WOWAUDIT_API_KEY.

Security model

A WoWAudit team API key can access the team's entire environment. The server applies these safeguards:

• The key is sent only as an Authorization: Bearer header. It is never put in a URL, result, or error.
• Only documented /v1/ routes are available. There is no arbitrary HTTP tool.
• Write tools are not advertised or callable unless WOWAUDIT_ENABLE_WRITES=true. The HTTP client independently blocks mutation requests while disabled. Set WOWAUDIT_WRITE_POLICY=raidlens-create-update-v1 to limit enabled mutations to character tracking and updates, raid creation and updates, and wishlist uploads.
• Destructive delete tools additionally require confirm: true on each call.
• Application tools are disabled unless WOWAUDIT_ENABLE_APPLICATIONS=true because applications may contain identities, questionnaire answers, and uploaded-file URLs.
• Tool annotations identify read-only, idempotent, and destructive operations to modern MCP clients.
• Responses are limited to 2 MiB by default. Adjust WOWAUDIT_MAX_RESPONSE_BYTES only when necessary.
• GET responses are cached in process for 30 seconds. Successful writes clear the cache.

Enabling application tools does not provide channel authorization. A Discord integration must enforce officer-only access before exposing those tools. Similarly, a multi-guild bot must bind its trusted Discord guild ID to the correct WoWAudit credential outside model-controlled tool arguments.

Configuration

Variable	Default	Purpose
WOWAUDIT_API_KEY	required unless FD is used	Team API key, preserved without trimming
WOWAUDIT_API_KEY_FD	unset	Inherited API key descriptor, 1 to 1024
WOWAUDIT_BASE_URL	https://api.wowaudit.com	API origin
WOWAUDIT_REQUEST_TIMEOUT_MS	30000	Request timeout, 5,000 to 120,000 ms
WOWAUDIT_MAX_RESPONSE_BYTES	2097152	Maximum JSON response, 64 KiB to 10 MiB
WOWAUDIT_ENABLE_WRITES	false	Permit POST, PUT, and DELETE tools
WOWAUDIT_WRITE_POLICY	unset	Restrict writes to raidlens-create-update-v1
WOWAUDIT_ENABLE_APPLICATIONS	false	Permit sensitive application tools

The default configuration exposes 11 non-sensitive GET tools. Setting WOWAUDIT_ENABLE_APPLICATIONS=true adds the two read-only application tools. Setting WOWAUDIT_ENABLE_WRITES=true adds mutation tools; leave it unset for a strictly read-only MCP surface. For RaidLens, also set WOWAUDIT_WRITE_POLICY=raidlens-create-update-v1. This policy exposes the 11 non-sensitive GET tools plus only wowaudit_track_character, wowaudit_update_character, wowaudit_create_raid, wowaudit_update_raid, and wowaudit_upload_wishlist when writes are enabled. All application tools are suppressed regardless of WOWAUDIT_ENABLE_APPLICATIONS, and all other mutations remain absent and uncallable. Unknown non-empty policy values prevent startup. Omitting the policy preserves the existing general write surface for current consumers.

Tools

Mutation tools shown below are only registered when WOWAUDIT_ENABLE_WRITES=true and permitted by WOWAUDIT_WRITE_POLICY. Application tools are only registered when WOWAUDIT_ENABLE_APPLICATIONS=true and no policy suppresses them.

Team and roster

Tool	API operation
wowaudit_get_team	GET /v1/team
wowaudit_get_period	GET /v1/period
wowaudit_list_characters	GET /v1/characters
wowaudit_track_character	POST /v1/characters
wowaudit_update_character	PUT /v1/characters/{id}
wowaudit_untrack_character	DELETE /v1/characters/{id}

Activity and attendance

Tool	API operation
wowaudit_list_historical_data	GET /v1/historical_data
wowaudit_get_character_history	GET /v1/historical_data/{id}
wowaudit_get_attendance	GET /v1/attendance

Raids and signups

Tool	API operation
wowaudit_list_raids	GET /v1/raids
wowaudit_get_raid	GET /v1/raids/{id}
wowaudit_create_raid	POST /v1/raids
wowaudit_update_raid	PUT /v1/raids/{id}
wowaudit_delete_raid	DELETE /v1/raids/{id}

wowaudit_update_raid supports status and schedule changes, encounter enable/disable lists, signup statuses, comments, role/class overrides, selected status, and encounter-specific selections.

Wishlists and loot

Tool	API operation
wowaudit_list_wishlists	GET /v1/wishlists
wowaudit_get_character_wishlist	GET /v1/wishlists/{id}
wowaudit_upload_wishlist	POST /v1/wishlists
wowaudit_delete_wishlist	DELETE /v1/wishlists/{id}
wowaudit_get_loot_history	GET /v1/loot_history/{seasonId}

The all-character wishlist and loot endpoints can be large. Prefer character-specific calls and use limit on collection tools where possible.

Applications

Tool	API operation
wowaudit_list_applications	GET /v1/applications
wowaudit_get_application	GET /v1/applications/{id}
wowaudit_update_application	PUT /v1/applications/{id}
wowaudit_delete_application	DELETE /v1/applications/{id}

Applications are separately gated by WOWAUDIT_ENABLE_APPLICATIONS=true. Mutating them also requires WOWAUDIT_ENABLE_WRITES=true. The raidlens-create-update-v1 policy suppresses every application tool regardless of these flags.

Result envelope

Successful tools, including wowaudit_get_team, return the canonical { data, meta } envelope consumed by RaidLens:

{
  "data": {
    "teamId": "42",
    "teamDisplayName": "RaidLens Team"
  },
  "meta": {
    "endpoint": "/v1/team",
    "method": "GET"
  }
}

wowaudit_get_team validates the upstream numeric id and name, converts the ID to a string, and returns only teamId (1 to 128 characters) and teamDisplayName (1 to 200 characters). Other upstream team fields are not exposed.

Collection tools accepting limit additionally report totalItems, returnedItems, and truncated. The limit is applied after WoWAudit responds because the public API does not document server-side pagination.

Errors return isError: true, structured { "error": "..." }, and a text fallback. Upstream errors also include kind, HTTP status, and retryAfterSeconds when available.

Development

npm run dev
npm test

Tests compile the server, verify both modern and legacy protocol negotiation, inspect all tool schemas and annotations, exercise security gates, and test the HTTP client without using a real API key.

For a small live read-only check:

npm run test:live

The live smoke test calls team, period, roster, and raid-list endpoints. It never invokes application or write tools.

WoWAudit API caveats

• The public documentation defines no pagination or rate-limit contract.
• The documentation primarily supplies response examples rather than strict reusable schemas, so payload fields may evolve.
• The embedded documentation contains a development-looking server URL. This project uses the confirmed production origin https://api.wowaudit.com by default.
• WoWAudit accepts an API key in a query parameter, but this server deliberately uses only the authorization header to reduce credential leakage.

License

MIT, copyright WoWAudit MCP Server contributors.