Wynncraft MCP

A TypeScript MCP server exposing 40 Wynncraft v3 data operations, with 15 optional Wynnventory market and reward-pool tools over stateless Streamable HTTP. Runs locally or as a Node 22 Function on Gigadrive Network. Unofficial; not affiliated with Wynncraft.

Player profiles and characters, guilds and territories, item and ingredient searches, recipes, ability trees, aspects, classes, map data, leaderboards, search, and news are covered. Wynnventory adds third-party observed market listings, price statistics/history, rankings, loot/raid pools and gambits when configured. The generated catalogue maps each tool to its API route.

Connect to the hosted server

MCP endpoint: https://wynncraft-mcp.gigadrive.app/mcp

Transport: Streamable HTTP · Authentication: Wynncraft OAuth

No clone, Node.js installation, API key, Upstash account or Wynncraft application setup is needed to use this hosted instance. Your MCP client opens a browser to sign in with Wynncraft, then asks you to approve the connection.

Codex

codex mcp add wynncraft --url https://wynncraft-mcp.gigadrive.app/mcp
codex mcp login wynncraft
codex mcp list

Alternatively, add this to your Codex config.toml, then run codex mcp login wynncraft:

[mcp_servers.wynncraft]
url = "https://wynncraft-mcp.gigadrive.app/mcp"

See the official Codex MCP guide.

Claude Code

claude mcp add --transport http --scope user wynncraft https://wynncraft-mcp.gigadrive.app/mcp
claude mcp login wynncraft

You can also run /mcp inside Claude Code and choose the server's authentication option. See the official Claude Code MCP guide.

Other MCP clients

Add a remote Streamable HTTP server using the endpoint above and complete OAuth when prompted. The client must support OAuth discovery, public dynamic client registration, PKCE S256 and resource indicators. Do not paste your Wynncraft application secret or account token into the client.

Try asking: “Look up my linked Wynncraft profiles”, “Show the combat leaderboard”, or “Find legendary mage weapons around level 80”. Use a new chat or reconnect if your client has not refreshed its tools list. Access tokens last 24 hours; sign in again when the client requests it.

The hosted instance is a community service with no uptime guarantee. Data returned to your MCP client can enter its chat history and AI processing; review your client's privacy/retention settings before authorizing private character data. Hosting your own instance is covered below.

Related MCP server: mcp-server-runescape

Run locally

Requires Node.js 22.14 or newer.

npm ci
cp .env.example .env.local
npm run dev

Connect an MCP client to http://localhost:3000/mcp using Streamable HTTP. No database or account is needed in anonymous mode. GET /healthz checks process health.

For a compiled build:

npm run build
npm start

Example Claude Code configuration for anonymous mode:

claude mcp add --transport http wynncraft http://localhost:3000/mcp

Trade-market data from Wynnventory

The optional integration uses Wynnventory's documented read-only v2 API. It adds 15 tools for observed listings, prices/history, rankings, loot/raid pools and gambits. Source attribution, observation timestamps, sample counts and data-quality caveats are preserved: these are community-observed asking prices, not confirmed completed sales or a complete live market feed.

Self-hosters can obtain a read-only application key, accurately describe the intended MCP use, and set WYNNVENTORY_API_KEY in runtime secrets. Hosted OAuth or MCP_API_KEY must also be configured to protect the shared application quota. No Wynncraft token is shared with Wynnventory. Without this optional key, its tools are hidden and the original 40-tool catalogue is unchanged; with it, there are 55 tools. Reconnect clients after enabling it.

See access/terms findings and alternative-source comparison and the Wynnventory tool catalogue. We found a documented third-party API access path, but no separate public terms granting unrestricted redistribution; no maintainer endorsement is implied.

Authentication modes

A public-mode flag is an operator assertion: this server cannot verify that the Wynncraft token's Public Mode is enabled. Keep private tokens behind authentication. In API-key mode clients send Authorization: Bearer <MCP_API_KEY>; the key is not the Wynncraft token.

Hosted OAuth lets anyone connect their own Wynncraft account. The client discovers OAuth metadata, registers using PKCE, signs in with Wynncraft, and approves the named MCP client on this server's consent screen. MCP clients receive a separate opaque access token; Wynncraft access tokens stay encrypted in the shared store. See OAuth setup and design.

Caching and client safety

OAuth discovery documents use Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=60, so browsers and the Gigadrive CDN can reuse user-independent metadata. Root and path-specific protected-resource discovery are both available. MCP traffic, authentication failures, cookies, consent, registration, token exchange, revocation and errors use no-store; unauthorized responses are never shared by the CDN.

The server publishes a friendly title, description, icon and source URL, validated tool input/output schemas, explicit read-only annotations and correct OAuth capabilities. Unknown tools return a protocol error; input and upstream failures return tool errors. It uses issuer identification on authorization responses, audience-bound tokens, PKCE, browser-bound state, explicit client consent and bounded upstream requests/responses.

MCP HTTP traffic has a per-process limit of 180 requests per minute per IP, in addition to Wynncraft's own buckets and OAuth endpoint limits. When the system GIGADRIVE_URL is present, the server trusts one proxy hop, matching Gigadrive's sanitized forwarding contract. Other deployments default to zero. TRUST_PROXY_HOPS explicitly overrides this (including 0); use only the verified proxy chain so forwarded client addresses cannot be spoofed. For deployments requiring global quotas, enforce them at the hosting edge; per-process limits are not distributed quotas.

Stateless behavior

Each MCP POST creates a new server and transport. Responses are JSON, no session IDs are issued, and no sticky sessions or in-process game caches are used. GET subscriptions and DELETE sessions return 405. This is Streamable HTTP using its JSON response mode, not the legacy SSE transport.

Anonymous and shared-token modes have no application storage. Hosted OAuth needs shared records to enforce one-time codes, consent and token revocation; every application instance remains disposable. A Gigadrive Redis sidecar is local to each Function copy and loses data with that copy, so it cannot provide the shared OAuth store for autoscaling.

Working with tools

Use wynncraft_player_getPlayer with { "username": "Salted", "fullResult": true } or wynncraft_item_searchItems with { "body": { "query": "Wand", "tier": "legendary" }, "page": 1 }. Filter enums are validated from Wynncraft's spec; use wynncraft_item_getItemMetadata to discover supported filters.

The booleans fullResult, full_result and static produce Wynncraft's required bare query flags, not =true. Paths accept names with spaces and Unicode while rejecting traversal and path separators.

Tools return {status, ok, metadata, data} with read-only hints, structured content, and safe cache/rate-limit headers. API errors include the original JSON and status with isError: true, including ambiguous matches (300), privacy failures (403), and throttling (429). Requests time out after 20 seconds and do not retry automatically. Respect retry-after or ratelimit-reset in tool results. Wynncraft currently documents separate 50 RPM guest / 120 RPM authenticated buckets; limits may change.

Large results are bounded to 8 MiB upstream and 128 KiB per tool response. Use the API's page parameter first. The optional view argument selects and slices a response locally:

{ "view": { "pointer": "/someSubtree", "offset": 0, "limit": 20 } }

pointer follows RFC 6901 (~1 for /, ~0 for ~). Slicing objects preserves their keys; projection.nextOffset indicates more entries. Projection doesn't reduce the upstream download, change upstream pagination, or silently truncate results. Remote game/player text and HTML are untrusted content.

Deploy to Gigadrive Network

gigadrive.yaml selects dist/index.js, Node 22, 512 MB, a 30-second invocation limit, and a catch-all route. Gigadrive detects Express, runs npm run build, imports the compiled entrypoint, and captures app.listen().

1. Run npm ci && npm run check.

2. PUBLIC_URL is optional: it overrides Gigadrive's system GIGADRIVE_URL, which otherwise supplies the HTTPS origin. Outside Gigadrive the fallback is http://localhost:PORT. Set PUBLIC_URL explicitly for a stable custom domain, for example https://wynncraft.example.com. The server checks the incoming Host header against the resolved origin; use the same canonical hostname for OAuth. GIGADRIVE_URL is unique to each deployment, so its callback must be registered in Wynncraft again when that URL changes. A stable PUBLIC_URL avoids this.

3. Set runtime secrets through the Gigadrive console, CLI, or API. Do not put secrets in gigadrive.yaml or commit .env.local.

4. Set ALLOWED_ORIGINS to a comma-separated list of browser client origins if needed; otherwise only PUBLIC_URL is allowed. Native clients without Origin are accepted. OAuth token/registration endpoints use the SDK's OAuth CORS handling.

5. Run gigadrive login, then gigadrive deploy from this repository.

6. For hosted OAuth, follow OAuth setup, including Upstash REST credentials.

7. Connect clients to https://your-host/mcp; verify /healthz and OAuth discovery if enabled.

A production instance is already deployed on Gigadrive Network at the hosted MCP endpoint. The steps above are for hosting your own instance, which needs its own Wynncraft application and runtime secrets. See the Gigadrive Network documentation for platform setup and configuration.

Development

npm run check       # strict TypeScript, HTTP/OAuth regression tests, build
npm run api:update  # refresh official Wynncraft schemas and coverage table
npm run wynnventory:update # refresh optional Wynnventory schemas
npm run probe       # check the hosted endpoint without user credentials
npm audit
npm run test:browser # install Chromium first with npx playwright install chromium

The generated schemas resolve request types from Wynncraft's official OpenAPI spec. The spec's token request content type differs from the endpoint's prose; the OAuth implementation follows the endpoint documentation and sends URL-encoded form data. Token exchange is never exposed as an MCP tool.

The repository contains no private hosting source or production credentials. The source repository is public and MIT licensed. package.json remains marked private to prevent accidental npm publishing.

The adversarial review used Claude Opus 5.5 via CLI. See review and validation notes.

Repository maintenance

CI runs TypeScript/build checks on Node 22 and 24, real Redis tests, browser OAuth tests, and a dependency audit. Dependabot updates npm dependencies and pinned GitHub Actions weekly. CodeQL scans main, pull requests and the weekly schedule. Main is protected by an active ruleset requiring PRs, CI and CodeQL results. See GitHub configuration for applied settings and the one-command public-repository setup.

Sources

• Wynncraft API docs

• Wynncraft OpenAPI

• Wynncraft application setup

• Wynncraft OAuth authorization

• Wynncraft OAuth token exchange

• Wynnventory API v2

• Wynnventory application API keys

• MCP Streamable HTTP

• Gigadrive Network documentation

Review API terms and retention responsibilities before operating a public instance or enabling private-data access.

MIT licensed. See LICENSE.