Skip to main content
Glama

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_get tool 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)

get_account, get_wallet, get_bank, get_materials, get_shared_inventory, list_characters, get_character, find_items, get_account_achievements, get_unlocks, get_wizards_vault, get_trading_post, get_pvp, get_daily_rotations, estimate_account_value

Game data

search, get_game_data, get_prices, get_listings, gem_exchange, find_recipes, api_get

History

take_snapshot, list_snapshots, get_snapshot, list_tracked_stats, stat_history, item_history, currency_history, achievement_history, character_history, unlock_history, compare_snapshots, progress_report

Misc

server_status; prompts weekly_review and item_tracking

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 -- serve

Other 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 / GW2_API_KEY_FILE

–

GW2 API key. Without it, only public data is available and no snapshots are taken.

GW2MCP_DB

$STATE_DIRECTORY or $XDG_DATA_HOME/gw2mcp/gw2mcp.sqlite3

SQLite database

GW2MCP_SNAPSHOT_INTERVAL

3600

Seconds between snapshots (0 disables them)

GW2MCP_SNAPSHOT_VALUE

true

Record the trading post value of all items with each snapshot

GW2MCP_LANG

en

en, de, es, fr, zh

GW2MCP_CATALOG_TTL_DAYS

7

Cache lifetime for public game data

GW2MCP_TRANSPORT

stdio

stdio or http

GW2MCP_HOST / GW2MCP_PORT

127.0.0.1 / 8000

HTTP bind address

GW2MCP_HTTP_PATH

/mcp

MCP endpoint path

GW2MCP_AUTH_TOKEN / _FILE

–

Require Authorization: Bearer <token> (HTTP). Mandatory when binding to a non-loopback address. A configured but empty token is a startup error.

GW2MCP_ALLOWED_HOSTS

–

Extra accepted Host headers, comma separated (needed behind a reverse proxy)

GW2MCP_ALLOWED_ORIGINS

–

Extra accepted Origin headers

GW2MCP_SCHEMA_VERSION

latest

X-Schema-Version sent to the API

GW2MCP_LOG_LEVEL

INFO

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 tests

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Auction house analytics, market intelligence, crafting optimization, inventory valuation, farming routes, guild analytics, and token tracking — all through the Model Context Protocol.
      10
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying Guild Wars 2 game data including items and achievements via natural language, part of the Pipeworx MCP gateway.
      96 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Exposes 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.
      11
      MIT