dreamingazeroth-mcp

MCP server for Dreaming Azeroth, a WotLK 3.3.5a private server running AzerothCore + mod-playerbots. It gives an AI client — Claude Code, Claude Desktop, or anything else that speaks Model Context Protocol — read access to the realm's databases and, behind explicit opt-in gates, the ability to run GM commands, edit config and code, and apply content changes.

Companion repos: dreamingazeroth-gui (web panel and the AzerothCore install script) and dreamingazeroth-addons (client addons).

Designed to run on the server box itself: MySQL and SOAP are both reached over loopback, so nothing new has to be exposed to the network.

What it is not

This does not talk to Blizzard's Battle.net API. Everything comes from your own acore_auth / acore_characters / acore_world / acore_playerbots schemas and your live worldserver, so custom items, custom loot and bot activity all show up exactly as they are on your realm.

Capabilities

Four tiers, each independently enabled. Reads always work; everything else is off until you turn it on.

Tier	Env var	What it unlocks
read	— always on	Every database query: characters, accounts, guilds, items, quests, loot, auctions, logs, server status
soap	AC_ENABLE_SOAP	GM commands through the running worldserver: announce, kick, teleport, mail, reload, account admin, shutdown
write	AC_ENABLE_WRITE	Editing files inside AC_WRITABLE_PATHS, and applying SQL with automatic backups
exec	AC_ENABLE_EXEC	systemctl service control, CMake builds, mysqldump backups

A tool whose tier is disabled is still listed, so the model can see it exists — it just fails with the exact env var to set.

Tools

<details> <summary><b>Ops and monitoring</b> (read)</summary>

• ac_server_status — services, population, database reachability, realm list, live SOAP banner
• ac_online_players — who is connected, with real players separated from RNDBOT playerbots
• ac_population_report — accounts, characters by level/class/race/faction, gold totals
• ac_server_logs — tail Server.log / Auth.log or the systemd journal, with a contains filter
• ac_db_health — schema sizes, largest tables, MySQL connection state
• ac_account_lookup — accounts by name/email/id/IP with GM level, bans and characters </details>

<details> <summary><b>Players</b> (read)</summary>

• ac_character_search — partial-name search with level/class/online filters
• ac_character_profile — full profile, optionally with equipment, stats, talents, skills, social
• ac_character_inventory — equipped gear and bags joined to item_template
• ac_guild_info — guild details and roster, or every guild ranked by size
• ac_character_mail — inbox with money and item attachments </details>

<details> <summary><b>Game content</b> (read)</summary>

• ac_item_search / ac_item_details — items, plus what drops them, who sells them, which quests reward them
• ac_creature_search — NPCs with loot tables and spawn points
• ac_quest_lookup — quests with objectives and rewards
• ac_spell_lookup — server-side spell data (limited by design; see Known limits)
• ac_db_describe — tables and columns, for confirming schema before writing SQL
• ac_sql_query — read-only SELECT escape hatch for anything not covered </details>

<details> <summary><b>Economy</b> (read)</summary>

• ac_auction_search — AH price statistics per item, split by bot vs player sellers
• ac_economy_report — gold in circulation, wealthiest characters, guild banks, gold in mail
• ac_playerbots_status — bot population, level spread, and their share of AH supply </details>

<details> <summary><b>GM commands</b> (soap)</summary>

• ac_gm_commands — the catalogue of runnable commands and their parameters
• ac_gm_command — run one by key with typed arguments
• ac_announce — broadcast chat text or an on-screen banner
• ac_player_action — kick, revive, summon, teleport an online character
• ac_send_mail — mail gold and items (the safe way to grant anything)
• ac_reload — reload worldserver.conf or one world table
• ac_server_shutdown — graceful shutdown/restart with a player countdown
• ac_account_admin — create accounts, reset passwords, set GM level, ban/unban
• ac_save_all — flush online characters to MySQL before reading their rows </details>

<details> <summary><b>Code, config and content</b> (write / exec)</summary>

• ac_server_layout — paths, installed modules, enabled capabilities, and the workflow for each kind of change
• ac_list_files / ac_read_file — browse and read the source tree and configs
• ac_write_file — write inside the allowlist, keeping a timestamped .bak
• ac_apply_sql — transactional SQL with a dryRun mode and mysqldump backups
• ac_read_config — grep settings out of .conf files without dumping them whole
• ac_service_control — status always; start/stop/restart with exec
• ac_build — CMake rebuild after a C++ change
• ac_git_status — read-only git against the source or a module </details>

Plus 5 prompts (health-check, investigate-player, add-content, tune-rates, economy-review) and two resources: ac://guide and ac://schema.

Two things that will bite you otherwise

Online characters are stale in the database. Worldserver holds logged-in characters in memory and only flushes on a timer and at logout. Any character query for someone who is online can be minutes behind. Call ac_save_all first when the exact number matters. Every affected tool says so in its output rather than letting you assume the row is current.

Never write to a live player's rows. UPDATE characters SET money = ... for someone who is online gets silently overwritten at the next save — the in-memory copy wins. Grant items and gold with ac_send_mail, change accounts with ac_account_admin. Both go through the running worldserver, so the change sticks and the server's own bookkeeping stays correct.

Which path for which change

Change	How	Restart needed?
Content — items, loot, vendors, NPCs, quests	ac_apply_sql, then ac_reload on the table	No
A setting in worldserver.conf	ac_write_file, then ac_reload target config	Only for settings not re-read live
Module config, e.g. playerbots.conf	ac_write_file, then restart worldserver	Usually yes
C++ in the core or a module	ac_write_file, ac_build, restart	Yes

Reach for SQL before C++ — most gameplay changes on AzerothCore are data, and data changes apply live.

Install

On the server, as the user that owns the AzerothCore checkout:

git clone https://github.com/Pliskin92/dreamingazeroth-mcp.git
cd dreamingazeroth-mcp
./install/install-mcp.sh --with-systemd --start

The script builds, deploys to /opt/dreamingazeroth-mcp, creates .env from .env.example, pulls DB_PASS out of ~/azerothcore/.db_credentials, generates an MCP_AUTH_TOKEN, and installs the systemd unit. Re-running it is safe and never touches an existing .env.

Verify:

curl -s http://127.0.0.1:8080/readyz | jq

Enabling the write and exec tiers

Edit /opt/dreamingazeroth-mcp/.env:

AC_ENABLE_SOAP=true
SOAP_USER=panel_soap          # any GM account
SOAP_PASS=...

AC_ENABLE_WRITE=true
AC_WRITABLE_PATHS=/home/youruser/azerothcore/source/modules,/home/youruser/azerothcore/env/dist/etc

AC_ENABLE_EXEC=true

SOAP also needs SOAP.Enabled = 1 in worldserver.conf.

AC_ENABLE_WRITE needs the systemd unit to allow those paths — ProtectHome=read-only is on by default, so uncomment and adjust ReadWritePaths= in the unit file.

AC_ENABLE_EXEC needs passwordless sudo for the service actions:

# /etc/sudoers.d/dreamingazeroth-mcp
youruser ALL=(root) NOPASSWD: /bin/systemctl start azerothcore-worldserver, \
                              /bin/systemctl stop azerothcore-worldserver, \
                              /bin/systemctl restart azerothcore-worldserver, \
                              /bin/systemctl start azerothcore-authserver, \
                              /bin/systemctl stop azerothcore-authserver, \
                              /bin/systemctl restart azerothcore-authserver

Scope it to exactly those units. A blanket NOPASSWD: ALL would make the MCP endpoint equivalent to root on the box.

Connecting a client

Claude Code, over the LAN from your desktop:

claude mcp add --transport http dreamingazeroth \
  http://azeroth.local:8080/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

That needs HOST=0.0.0.0 and MCP_AUTH_TOKEN set in .env.

stdio, when the client runs on the server itself:

{
  "mcpServers": {
    "dreamingazeroth": {
      "command": "node",
      "args": ["/opt/dreamingazeroth-mcp/dist/index.js", "--stdio"]
    }
  }
}

Security

The endpoint can read your entire player database and, with the gates open, change the running realm. It binds to 127.0.0.1 by default.

• MCP_AUTH_TOKEN is mandatory for any non-loopback bind. The server logs a warning at startup if it is unset.
• azeroth is LAN-only (no public IP, no port forwarding — see the gui repo's TODO). Keep it that way; there is no reason to expose this to the internet.
• SOAP commands are an allowlist, not a passthrough. You pick a command by key and supply typed parameters — free-text command strings are never sent. This is deliberate: the previous version of this stack shipped a SOAP command-injection hole (see the uncompliantexperience audit referenced in the gui repo), and structuring the interface this way is what prevents that class of bug rather than trusting each call site to escape correctly.
• AzerothCore's console parser has no quoting. It splits arguments on whitespace, full stop — account create "My Name" pw really does create an account called "My. Arguments are typed bare / quoted / rest / int accordingly, and a value that cannot be expressed safely is rejected with an explanation instead of being mangled. Newlines and control characters are refused everywhere, since they could smuggle in a second command.
• File access is a realpath-checked allowlist. A symlink inside a writable root cannot be used to escape it.
• ac_sql_query is read-only — positive check for SELECT/SHOW/DESCRIBE/EXPLAIN, a keyword denylist for anything hidden in a subquery, and a row cap.
• Destructive tools require confirm: true. Not a substitute for the capability gates — a second, per-call deliberate step.

Known limits

• Spell data is mostly client-side. Stock AzerothCore reads spells from the client's DBC files; spell_dbc only holds custom or overridden entries. ac_spell_lookup returns what the server actually knows and says so when a spell is not there, rather than inventing an answer.
• Column names drift between forks. This targets the mod-playerbots/azerothcore-wotlk Playerbot branch. Where a schema difference is known — creature.id1 vs creature.id, talent_dbc vs Talent — it is handled, but run ac_db_describe before trusting a hand-written query.
• ac_build is slow. A full rebuild is tens of minutes and saturates CPU. It will degrade a live realm.
• acore_playerbots is module-owned. Read it; do not write it. mod-playerbots rewrites that schema on its own schedule.
• Multi-item mail sends one mail per item. The console parser cannot express several id:count pairs in one argument, so ac_send_mail splits them and says so in its result.

Development

npm install
npm run dev            # tsx watch, HTTP transport
npm run stdio          # stdio transport against a local .env
npm run typecheck
npm test

Layout:

src/
  ac/          AzerothCore integration: db pools, SOAP, file sandbox, process runner, WotLK constants
  tools/       MCP tools grouped by area (ops, characters, content, economy, admin, devops)
  util/        Cache, formatting, errors
  config.ts    Environment parsing and capability gates
  http.ts      Streamable HTTP transport, sessions, auth, CORS, health
  stdio.ts     stdio transport
  server.ts    Wires backends into an McpServer