GW2 MCP Server

Trading Post Mastery

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

Trading Post Mastery#

Turn your AI assistant into a Trading Post companion in about 30 minutes.

By the end of this tutorial, you will have:

Looked up live buy and sell prices for any item by name
Compared prices across multiple items in a single conversation
Checked gem-to-gold and gold-to-gem exchange rates
Reviewed your open buy orders and sell listings
Checked your Trading Post delivery box for uncollected items and coins
Browsed your recent transaction history

Prerequisites#

Before starting, make sure you have:

Know Your Account

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

Know Your Account#

Explore your Guild Wars 2 account through your AI assistant in about 30 minutes.

By the end of this tutorial, you will have:

Checked your wallet balances across all currencies
Browsed your bank vault, material storage, and shared inventory
Listed your characters and inspected one in detail
Looked up your account unlocks
Viewed your overall account information

Prerequisites#

Before starting, make sure you have:

The Getting Started tutorial complete (GW2 MCP server running with Claude Desktop or another AI client)
A GW2 API key with these scopes enabled: account, characters, inventories, wallet, unlocks

If you are not sure which scopes your key has, check at Guild Wars 2 API Key Management . For details on what each scope enables, see the API Scopes reference .

Crafting Assistant

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

Crafting Assistant#

Use your AI assistant as a crafting research companion – look up recipes, check material prices, and figure out whether to craft or buy from the Trading Post.

By the end of this tutorial, you will have:

Looked up a crafting recipe by item name
Retrieved detailed item metadata
Found recipes that use a specific material
Estimated the cost to craft an item
Compared crafting cost against the Trading Post buy price

Estimated time: 30 minutes

Daily Checklist

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

Daily Checklist#

Use your AI assistant as a daily companion to track Wizard’s Vault objectives, achievements, and instanced content clears – all without leaving your conversation.

By the end of this tutorial, you will have:

Checked your daily and weekly Wizard’s Vault objectives and tracked Astral Acclaim progress
Browsed the Wizard’s Vault reward listings
Looked up today’s daily achievements
Reviewed your raid, dungeon, and world boss completion for the current reset period

Estimated time: 20 minutes

Check Item Profitability

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

How to Check Item Profitability#

Goal: Determine whether flipping an item on the Trading Post is profitable after fees.

Time: Approximately 5 minutes

Prerequisites#

None – Trading Post prices are public data and do not require an API key.

You should be familiar with looking up item prices. If not, see the Trading Post Mastery tutorial first.

Steps#

1. Look up the item’s buy and sell prices#

Ask your AI: “What are the Trading Post prices for Mystic Coin?”

Track Your TP Orders

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

How to Track Your TP Orders#

Goal: View your current buy orders, sell listings, and recent transaction history on the Trading Post.

Time: Approximately 5 minutes

Prerequisites#

GW2 MCP Server connected to your AI assistant – see Getting Started
An API key with the tradingpost scope enabled – see API Key Scopes

Steps#

1. Check your current buy orders#

Ask your AI: “Show my current buy orders”

Your assistant uses the get_tp_transactions tool with type current/buys. For each open buy order, you will see:

Gem Exchange Rates

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

How to Check Gem Exchange Rates#

Goal: Look up current gem-to-gold and gold-to-gem conversion rates.

Time: Approximately 3 minutes

Prerequisites#

None – gem exchange rates are public data and do not require an API key.

Steps#

1. Check how many gems you can buy with gold#

Ask your AI: “How many gems can I get for 100 gold?”

Your assistant uses the get_gem_exchange tool with direction coins and the quantity in copper. Your assistant handles the conversion automatically – you just ask in gold.

Find Valuable Items in Your Bank

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

How to Find Valuable Items in Your Bank#

Goal: Identify items in your bank vault that are worth gold on the Trading Post, so you can sell them or make informed decisions about your storage.

Prerequisites#

GW2 MCP Server running and connected to your AI assistant – see Getting Started if you need setup help
A GW2 API key with account and inventories scopes enabled

Steps#

1. Ask your AI to check your bank contents#

Ask your AI: “What’s the most valuable stuff in my bank?”

Audit Your API Key

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

How to Audit Your API Key#

Goal: Check what permissions your GW2 API key has and understand which tools require which scopes, so you can fix authorization errors or set up a key with the right access.

Prerequisites#

GW2 MCP Server running and connected to your AI assistant – see Getting Started if you need setup help
A GW2 API key configured (any scopes – even a minimal key works for this check)

Steps#

1. Ask your AI what permissions your key has#

Ask your AI: “What permissions does my API key have?”

Compare Characters

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

How to Compare Characters#

Goal: View your character roster and compare details like gear, crafting levels, and builds across two or more characters.

Prerequisites#

GW2 MCP Server running and connected to your AI assistant – see Getting Started if you need setup help
A GW2 API key with account and characters scopes enabled

Steps#

1. List all your characters#

Ask your AI: “List my characters”

Your AI calls the get_characters tool without specifying a name. The response is a list of every character on your account – their names, just like the character selection screen in-game.

Crafting vs Buying

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

Crafting vs Buying#

Goal: Determine whether it is cheaper to craft an item yourself or buy it directly from the Trading Post.

Prerequisites#

None – all lookups use public GW2 API endpoints. No API key is required.

Steps#

1. Ask your AI for a cost comparison#

Ask your AI: “Is it cheaper to craft or buy Deldrimor Steel Ingot?”

You can use any craftable item name. The AI handles the entire multi-step analysis automatically.

Find Recipes for a Material

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

Find Recipes for a Material#

Goal: Find out what you can craft with a specific material you have in your inventory.

Prerequisites#

None – recipe and item lookups use public GW2 API endpoints. No API key is required.

Steps#

1. Ask your AI what uses a material#

Ask your AI: “What can I craft with Glob of Ectoplasm?”

Use the exact in-game name of the material you want to look up. The AI handles the multi-step lookup automatically.

Plan Your Wizard's Vault Session

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

How to Plan Your Wizard’s Vault Session#

Goal: Plan your daily Wizard’s Vault session efficiently by checking objectives, rewards, and your Astral Acclaim balance before you play.

Prerequisites#

GW2 MCP Server running and connected to your AI assistant – see Getting Started
A GW2 API key with account and progression scopes for personal progress tracking – see API Scopes
Without an API key, you can still view objective lists and reward catalogs, but you will not see your completion status or purchase history

Steps#

1. Check your daily objectives#

Ask your AI: “What are today’s Wizard’s Vault dailies?”

Track Raid and Dungeon Clears

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

How to Track Raid and Dungeon Clears#

Goal: See which raids, dungeons, and world bosses you have completed this reset period so you know what still has rewards available.

Prerequisites#

GW2 MCP Server running and connected to your AI assistant – see Getting Started
A GW2 API key with account and progression scopes – see API Scopes
All three tools in this guide require an API key. Without one, these lookups will not work.

Steps#

1. Check your raid clears#

Ask your AI: “Which raids have I cleared this week?”

Design Decisions

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

This page explains the major design decisions in the GW2 MCP Server and the reasoning behind them. Understanding these decisions will help you make sense of the codebase’s structure and anticipate how changes in one area affect others.

For the structural overview of the system itself, see Architecture .

json.RawMessage for variable structures#

The problem#

The Guild Wars 2 API returns deeply nested, polymorphic JSON. The /v2/items endpoint alone has over 20 item subtypes – Weapon, Armor, Consumable, Trinket, UpgradeComponent, and many more – each with a different details object. A Weapon’s details include damage_type, min_power, and max_power; an Armor’s details include weight_class and defense. Character data is similarly variable: equipment, skills, specializations, build tabs, and equipment tabs all carry deeply nested structures that differ by profession and game mode.

Guild Lookup

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

How to Look Up Guild Information#

Goal: Find a guild by name and view its public info, or access detailed guild data if you are the leader.

Time: Approximately 5 minutes

Prerequisites#

For public info (name, tag, level): No API key required.
For detailed data (members, stash, treasury, etc.): An API key with the guilds scope, and you must be the guild leader.

Steps#

1. Search for a guild by name#

Ask your AI: “Find the guild called Mighty Teapot”

Use Without an API Key

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

How to Use the Server Without an API Key#

Goal: Understand which tools work without an API key, so you can try the server before setting up authentication.

Time: Approximately 5 minutes to read; ongoing use

Prerequisites#

None. That is the point of this guide.

You need the GW2 MCP Server connected to an AI client (Claude Desktop, Claude Code, LM Studio, etc.), but no API key configured. See Getting Started for installation steps – you can skip Step 2 (creating an API key) and leave GW2_API_KEY empty or remove the env block entirely.

Wiki Search

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

How to Search the GW2 Wiki#

Goal: Search the official Guild Wars 2 wiki for game information directly through your AI assistant.

Time: Approximately 3 minutes

Prerequisites#

None. Wiki search is a public tool that works without an API key.

Steps#

1. Ask a wiki search question#

Ask your AI: “Search the wiki for Dragon Bash”

Your assistant calls the wiki_search tool with your query. The search runs against the official Guild Wars 2 wiki at wiki.guildwars2.com.

Add a New Tool

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

Add a New Tool#

Goal: Add a new MCP tool to the GW2 MCP Server, from API struct to registered handler.

Time: Approximately 20 minutes

This guide walks through adding a hypothetical get_titles tool that retrieves title metadata from the GW2 /v2/titles endpoint. The pattern shown here applies to any new tool.

Prerequisites#

Go 1.24+ installed
Repository cloned and building (make build passes)
Familiarity with the project architecture

Steps#

1. Define the response struct#

Open internal/gw2api/client.go and add a struct that matches the GW2 API response shape. Place it near the other game metadata types (after the Mini struct is a good location).

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.

Architecture

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

How the GW2 MCP Server is structured and why

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.

Configure MCP Clients

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

How to Configure MCP Clients#

Goal: Connect your MCP client to the GW2 MCP Server so you can query Guild Wars 2 data from your AI assistant.

Prerequisites#

Before starting, you should have:

A GW2 API key created at Guild Wars 2 API Key Management – see API Key Scopes for which permissions to enable
Either Docker installed or the gw2-mcp binary downloaded/built – see Getting Started for installation steps

Claude Desktop#

Open Claude Desktop and navigate to Settings > Developer > Edit Config. This opens the claude_desktop_config.json file.

Contribute

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

How to Contribute to GW2 MCP Server#

Goal: Set up a local development environment, run quality checks, and submit a pull request to the GW2 MCP Server project.

Time: Approximately 20 minutes for initial setup.

Prerequisites#

Before starting, you should have:

Go 1.24+ installed – verify with go version
Git installed and configured with your GitHub account
Make available on your system (GNU Make on Linux/macOS, or via Git Bash / MSYS2 on Windows)
A GitHub account with permissions to fork repositories

Development Setup#

1. Fork and clone the repository#

Fork the repository on GitHub, then clone your fork locally:

Getting Started

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

Getting Started#

Connect Claude Desktop to your Guild Wars 2 account in about 15 minutes.

By the end of this tutorial, you will have:

A running GW2 MCP server inside Docker
Claude Desktop configured to use it
Queried your GW2 wallet, looked up an item, and checked Trading Post prices – all through natural language

Prerequisites#

Before starting, make sure you have:

Docker Desktop installed and running (download here )
Claude Desktop installed (download here )
A Guild Wars 2 account

Step 1: Pull the server image#

Open a terminal and pull the GW2 MCP server Docker image:

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.