gw2mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
gw2mcp
An MCP server for the Guild Wars 2 API. It answers questions about your account in real time, and it records snapshots of the account on a schedule. With those snapshots it can also answer historical questions such as "How much gold did I make this week?", "When did I unlock Twilight's skin?" or "How did my ectoplasm stock change over the last three months?".
Features
Live account data: account, wallet, bank, material storage, shared inventory, characters (core, inventory, equipment, builds, crafting, …), achievements, all unlock collections, Wizard's Vault, trading post orders and history, PvP, daily and weekly completions, and an item-location finder.
Game data: name search over items, achievements, skins, currencies and other endpoints, using a local index. You can also look up any bulk endpoint by id, read trading post prices and order books, check the gem exchange rate and search recipes. A raw
api_gettool covers everything else.History: periodic snapshots go into SQLite. They cover stats (AP, gold, playtime, item value, fractal/WvW/PvP rank, mastery points, luck, unlock counts …), wallet, item counts (in total and per location), achievement progress, characters, and every unlock collection. Only changes are stored, so hourly snapshots stay small.
Transports: stdio for local clients, and streamable HTTP for remote use, with optional bearer-token auth and DNS-rebinding protection.
NixOS: a flake with a package, a NixOS module (hardened systemd service with an optional nginx reverse proxy and ACME) and a VM test.
Related MCP server: blizzard-wow-mcp
Tools
Area | Tools |
Account (live) |
|
Game data |
|
History |
|
Misc |
|
History tools take time references as ISO dates (2025-01-31, 2025-01-31T18:00:00Z), as
relative offsets (24h, 7d, 2w, 3mo, 1y), or as latest, first or a snapshot id.
Installation & usage
Create an API key at https://account.arena.net/applications. For full functionality, grant
these permissions: account, inventories, characters, wallet, unlocks, progression,
tradingpost, pvp, builds, wvw. When a permission is missing, the sections that need it
are skipped and reported in the snapshot's errors.
# with uv
uv run gw2mcp serve # stdio (default)
GW2MCP_TRANSPORT=http uv run gw2mcp serve --port 8765
# with nix
nix run github:<you>/gw2mcp -- serveOther commands:
gw2mcp snapshot # take one snapshot now and print it
gw2mcp snapshots --limit 10 # list recorded snapshots
gw2mcp index items skins # pre-build name-search indices (otherwise built on first search)Claude Code / Claude Desktop (stdio)
claude mcp add gw2 --env GW2_API_KEY=XXXX -- uv --directory /path/to/gw2mcp run gw2mcp serve{
"mcpServers": {
"gw2": {
"command": "uv",
"args": ["--directory", "/path/to/gw2mcp", "run", "gw2mcp", "serve"],
"env": { "GW2_API_KEY": "XXXX" }
}
}
}Remote (HTTP)
claude mcp add --transport http gw2 https://gw2.example.com/mcp --header "Authorization: Bearer <token>"With stdio, snapshots are only taken while the client keeps the server running. For continuous
history, run the HTTP server as a service (see NixOS below), or call gw2mcp snapshot from cron
or a systemd timer.
Configuration
All settings are environment variables. Secrets can also be read from <NAME>_FILE, or from
systemd credentials ($CREDENTIALS_DIRECTORY/gw2-api-key and $CREDENTIALS_DIRECTORY/auth-token).
Variable | Default | Description |
| – | GW2 API key. Without it, only public data is available and no snapshots are taken. |
|
| SQLite database |
|
| Seconds between snapshots ( |
|
| Record the trading post value of all items with each snapshot |
|
|
|
|
| Cache lifetime for public game data |
|
|
|
|
| HTTP bind address |
|
| MCP endpoint path |
| – | Require |
| – | Extra accepted |
| – | Extra accepted |
|
|
|
|
| Log level |
GET /healthz is always reachable without a token.
The raw api_get tool only reaches known API routes. Credential endpoints (createsubtoken, tokeninfo)
are blocked, and get_account omits the key's id from its token details.
NixOS
{
inputs.gw2mcp.url = "github:<you>/gw2mcp";
outputs = { nixpkgs, gw2mcp, ... }: {
nixosConfigurations.host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
gw2mcp.nixosModules.default
{
services.gw2mcp = {
enable = true;
apiKeyFile = "/run/secrets/gw2-api-key"; # e.g. from agenix / sops-nix
authTokenFile = "/run/secrets/gw2mcp-token";
snapshotInterval = 3600;
nginx = {
enable = true;
virtualHost = "gw2.example.com";
enableACME = true; # forceSSL follows enableACME
};
};
security.acme = { acceptTerms = true; defaults.email = "you@example.com"; };
networking.firewall.allowedTCPPorts = [ 80 443 ];
}
];
};
};
}The service runs as a DynamicUser with systemd sandboxing. Data is kept in /var/lib/gw2mcp,
and secrets are passed in with LoadCredential, so the secret files can stay root-only.
nginx proxies only the MCP path and /healthz, and turns off buffering for streaming responses.
The virtual host name is added to the server's allowed Host headers automatically. Other options:
host, port (8765), path, language, trackAccountValue, catalogTtlDays, allowedHosts,
logLevel, openFirewall, environment and nginx.extraLocationConfig (for example for IP allow lists).
The flake also exports overlays.default, which adds python3Packages.gw2mcp and pkgs.gw2mcp.
If your nixpkgs still ships mcp < 2.3, the overlay packages mcp 2.3 from pinned wheels.
nix build .#gw2mcp # builds the package and runs the unit tests
nix flake check # also runs the NixOS VM test (nginx + auth + MCP session)How history is stored
Each snapshot adds a row to snapshots. Tracked values are written to
observations(kind, key, snapshot_id, value) only when they change, and null marks a value
that disappeared. The value at any snapshot is the latest observation at or before it. If a
section fails (for example because of a missing permission or an API outage), its kinds are left
out of that snapshot, so the previous values carry forward instead of looking like losses. Item
totals are only recorded when every inventory source was read successfully.
Kinds: stat, wallet, item, item_location (<item_id>|<location>), achievement,
character, unlock:<collection>.
The achievement point total is computed from tier points, repeats and point caps, plus daily and monthly AP. Treat it as an approximation of the in-game value. The item value counts every copy of a tradeable item at trading post prices, including account-bound copies.
Development
uv sync
uv run pytest --cov # tests use an in-memory fake of the GW2 API; no network needed
uv run ruff check src tests && uv run ruff format --check src testsTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Query your trades, stats, and journal in EdgeLock and log new entries by chat. OAuth; free account.
Recurring crypto treasury snapshots with balances, activity and gas state.
Historical crypto wallet holdings, valuations and CSV exports. OAuth; paid own-wallet scans.
Query cryptocurrency on-chain data, OHLCV prices, market data, and Research & QuickTake insights.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceProvides comprehensive World of Warcraft guild analytics, player character analysis, and auction house market data through the Blizzard Battle.net API. Supports both Retail and Classic WoW with real-time market insights, guild roster management, and demographic analytics.-
- AlicenseAqualityCmaintenanceAuction house analytics, market intelligence, crafting optimization, inventory valuation, farming routes, guild analytics, and token tracking — all through the Model Context Protocol.10MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying Guild Wars 2 game data including items and achievements via natural language, part of the Pipeworx MCP gateway.96 npmMIT
- AlicenseAqualityCmaintenanceExposes the WoWAudit API as structured tools for guild management, including roster, raid planning, attendance, wishlists, loot history, and applications, with read-only mode by default and optional write support.11MIT