Reference on GW2 MCP Server

API Key Scopes

Mon, 01 Jan 0001 00:00:00 +0000

API Key Scopes#

GW2 MCP Server tools that access account-specific data require a Guild Wars 2 API key with specific permission scopes. This page lists the scopes required by each authenticated tool and describes each available scope.

Tool Scope Requirements#

Every authenticated tool requires the account scope plus zero or more additional scopes. Tools not listed here do not require an API key.

Tool	Required Scopes
`get_account`	`account`
`get_account_dailies`	`account`, `progression`
`get_account_progress`	`account`, `progression`
`get_account_unlocks`	`account`, `unlocks`
`get_bank`	`account`, `inventories`
`get_characters`	`account`, `characters`
`get_guild_details`	`account`, `guilds`
`get_inventory`	`account`, `inventories`
`get_materials`	`account`, `inventories`
`get_token_info`	any valid key
`get_tp_delivery`	`account`, `tradingpost`
`get_tp_transactions`	`account`, `tradingpost`
`get_wallet`	`account`, `wallet`
`get_wizards_vault_listings`	`account`, `progression`
`get_wizards_vault_objectives`	`account`, `progression`

If the API key is missing a required scope, the GW2 API returns an authorization error.

Caching

Mon, 01 Jan 0001 00:00:00 +0000

The GW2 MCP Server maintains an in-memory cache to reduce redundant calls to the Guild Wars 2 API. Each data category has a fixed time-to-live (TTL) after which the cached entry expires and the next request fetches fresh data from the API.

Cache TTL Values#

All TTL constants are defined in internal/cache/manager.go.

Static Game Data#

Constant	TTL	Applies To
`StaticDataTTL`	365 days	Currency definitions
`ItemDataTTL`	24 hours	Item metadata, skin metadata
`RecipeDataTTL`	24 hours	Recipe details, recipe search results
`AchievementDataTTL`	24 hours	Achievement details
`ColorDataTTL`	24 hours	Dye color definitions
`MiniDataTTL`	24 hours	Miniature definitions
`MountDataTTL`	24 hours	Mount skin and type definitions (defined but not currently used in client)
`DungeonDataTTL`	24 hours	Dungeon and raid definitions (defined but not currently used in client)
`WikiDataTTL`	24 hours	Wiki search results, wiki page content

Account Data#

All account data keys include a SHA-256 hash of the API key for per-key isolation.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Environment variables, startup behavior, security properties, and error messages for the GW2 MCP Server.

Environment Variables#

Variable	Required	Description
`GW2_API_KEY`	No	Guild Wars 2 API key. Enables authenticated tools that access account-specific data. Created at account.arena.net/applications . See API Key Scopes for the permissions each tool requires.

GW2_API_KEY is the only environment variable the server reads.

Startup Behavior#

The server reads GW2_API_KEY from the environment once at startup and passes it to the API client. The key is not re-read during the server’s lifetime.

Tools Reference

Mon, 01 Jan 0001 00:00:00 +0000

Tools Reference#

Complete specification for all 37 MCP tools exposed by the GW2 MCP Server. Each tool is invoked via the MCP tools/call method over stdio. For authentication requirements, see API Scopes . For cache behavior, see Caching . For client setup, see How to Configure MCP Clients .

Overview#

Wiki#

Tool	Auth	Description
`wiki_search`	None	Search Guild Wars 2 wiki for information about game content

Account#

Tool	Auth	Description
`get_account`	`GW2_API_KEY`	Get account information including name, world, guilds, and access
`get_wallet`	`GW2_API_KEY`	Get wallet information including all currencies
`get_bank`	`GW2_API_KEY`	Get bank vault contents with item names
`get_materials`	`GW2_API_KEY`	Get material storage contents with item names
`get_inventory`	`GW2_API_KEY`	Get shared inventory slot contents with item names
`get_characters`	`GW2_API_KEY`	List characters or get details for a specific character
`get_account_unlocks`	`GW2_API_KEY`	Get account unlocked IDs by type
`get_account_progress`	`GW2_API_KEY`	Get account progress data by type
`get_account_dailies`	`GW2_API_KEY`	Get completed daily content IDs by type
`get_token_info`	`GW2_API_KEY`	Get API key name and permission scopes

Trading Post#

Tool	Auth	Description
`get_currencies`	None	Get information about Guild Wars 2 currencies
`get_tp_prices`	None	Get aggregated best buy/sell prices for items
`get_tp_listings`	None	Get full order book listings for items
`get_gem_exchange`	None	Get gem exchange rates between coins and gems
`get_tp_delivery`	`GW2_API_KEY`	Get items and coins awaiting pickup from the Trading Post
`get_tp_transactions`	`GW2_API_KEY`	Get current orders or completed transactions from the past 90 days

Game Data#

Tool	Auth	Description
`get_items`	None	Get item metadata for given item IDs
`get_skins`	None	Get skin metadata for given skin IDs
`get_recipes`	None	Get recipe details for given recipe IDs
`search_recipes`	None	Search for recipe IDs by input or output item ID
`get_achievements`	None	Get achievement details for given achievement IDs
`get_daily_achievements`	None	Get today’s and tomorrow’s daily achievements

Wizard’s Vault#

Tool	Auth	Description
`get_wizards_vault`	None	Get current Wizard’s Vault season information
`get_wizards_vault_objectives`	Optional	Get Wizard’s Vault objectives; authenticated endpoint shows account progress
`get_wizards_vault_listings`	Optional	Get Wizard’s Vault reward listings; authenticated endpoint shows purchase status

Guilds#

Tool	Auth	Description
`get_guild`	None	Get public guild information (name, tag, level)
`search_guild`	None	Search for a guild by name
`get_guild_details`	`GW2_API_KEY`	Get detailed guild data (log, members, ranks, stash, etc.)

Game Metadata#

Tool	Auth	Description
`get_colors`	None	Get dye color metadata for given color IDs
`get_minis`	None	Get miniature metadata for given mini IDs
`get_mounts_info`	None	Get mount skin or mount type metadata for given IDs
`get_game_build`	None	Get the current Guild Wars 2 game build number
`get_dungeons_and_raids`	None	Get dungeon or raid metadata for given IDs

Composite Tools#

Tool	Auth	Description
`get_item_by_name`	None	Look up a GW2 item by name via wiki search, then return full item details
`get_item_recipe_by_name`	None	Find crafting recipes for a GW2 item by name via wiki search
`get_tp_price_by_name`	None	Get Trading Post prices for an item by name via wiki search

Wiki#

wiki_search#

Search Guild Wars 2 wiki for information about game content.