# Wow Server Mcp

> Advanced WoW Server MCP - Universal World of Warcraft repack management toolkit.

- **Type:** MCP server
- **Install:** `agentstack add mcp-timoinglin-wow-server-mcp`
- **Verified:** Pending review
- **Seller:** [timoinglin](https://agentstack.voostack.com/s/timoinglin)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [timoinglin](https://github.com/timoinglin)
- **Source:** https://github.com/timoinglin/wow-server-mcp

## Install

```sh
agentstack add mcp-timoinglin-wow-server-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> ### 🐉 New from me — **WOW Legends**: a free WotLK 3.3.5a repack
> Run your own living **Wrath of the Lich King (3.3.5a)** world in a few clicks — hundreds of AI-driven bots, an AI companion that chats back, hardcore mode, and a one-click installer.
>
> **▶ Check it out → [wow-legends.eu](https://wow-legends.eu)**

---

# WoW Server MCP

[](https://github.com/timoinglin/wow-server-mcp/releases)
[](https://github.com/timoinglin/wow-server-mcp/actions/workflows/build.yml)
[](https://modelcontextprotocol.io)
[](LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)

A local **[MCP](https://modelcontextprotocol.io)** server that lets any MCP-compatible AI client (Claude, Codex, Cursor, etc.) manage a standalone World of Warcraft private server. Built and tested for **Cata / MoP repacks** with MySQL — works with any repack once configured.

> **TL;DR:** if you can do it in-game as a GM or via the database, the agent can do it for you.

> 💛 **Using the WoW Server MCP?** It's free and open-source, built and maintained in spare time. If it's saved you hours of server admin — or you'd like to see it keep growing — a coffee genuinely helps. See [Support the Project](#support-the-project).
>
> [](https://ko-fi.com/kneuma)

## Table of Contents

- [What the Agent Can Do](#what-the-agent-can-do)
- [Why an MCP Instead of Raw Credentials?](#why-an-mcp-instead-of-raw-credentials)
- [Demo Videos](#demo-videos)
- [Quick Start](#quick-start)
- [Dynamic Schema (Any Expansion)](#dynamic-schema-any-expansion)
- [Available Tools (82 total)](#available-tools-82-total)
- [Bug-Hunting / DB Integrity](#bug-hunting--db-integrity)
- [Database Backups](#database-backups)
- [Updating](#updating)
- [Prerequisites](#prerequisites)
- [Project Structure](#project-structure)
- [Releases](#releases)
- [Support the Project](#support-the-project)

---

## What the Agent Can Do

Once connected, the AI gets full control over your WoW server through natural language.

| Category | Capabilities |
|:---|:---|
| 🚀 **Server Control** | Start / stop / restart MySQL, authserver, worldserver |
| 🗄️ **Database** | Run any SELECT, INSERT, UPDATE, DELETE — or use scoped helpers |
| 👤 **Accounts** | Create accounts, set GM levels, grant Donation Points |
| 🐉 **NPCs** | Clone templates, set flags, manage vendors, gossip menus, waypoints |
| 📜 **Quests** | Create quests, assign giver/ender NPCs, manage rewards & relations |
| 💎 **Loot** | Add/remove creature drops, search which mobs drop an item |
| 🔮 **Spells & Events** | Look up spells from `spell_dbc`, view world events |
| 📍 **Teleports** | Find coordinates and map positions for NPC placement |
| ⚙️ **Config** | Edit rates, caps, realm settings in `worldserver.conf` |
| 📡 **Remote Access** | Send any RA command — anything you'd type in the worldserver console |
| 📊 **Monitoring** | Uptime, online players, DB statistics |
| 💾 **Backups** | Full or table-specific `mysqldump` with `WHERE` clause support |
| 🔬 **Forensics** | Deep-inspect creatures / gossip chains / SmartAI / loot, find orphan FK refs, verify ScriptNames against core source |

## Why an MCP Instead of Raw Credentials?

You *could* hand the AI your DB password and RA port and let it figure things out — but a dedicated MCP is significantly better:

| | Raw Credentials | MCP Server |
|:---|:---|:---|
| **Reliability** | Agent guesses SQL column names | Pre-built queries matched to your exact schema |
| **Speed** | Writes + debugs SQL from scratch every time | Instant tool calls — no trial and error |
| **Safety** | Unrestricted DB access (`DROP TABLE` is one prompt away) | Scoped tools with built-in validation and `WHERE` guards |
| **Token cost** | Burns tokens on boilerplate SQL and schema reads | Just the tool name and parameters |
| **Consistency** | Different results depending on the model's mood | Same reliable output every time |
| **Portability** | Prompts break when you switch AI clients | Works with any MCP-compatible client |

## Demo Videos

| What | Link |
|:---|:---|
| 🛠️ How to set it up | [Watch on YouTube](https://youtu.be/-z8X3xofVEA) |
| 🛒 Add a vendor to the world | [Watch on YouTube](https://youtu.be/LAPUUya4cBg?si=-Vc6WV5icljwZToh) |
| ⚔️ Update NPC stats | [Watch on YouTube](https://youtu.be/tQlK2906EP8?si=W6zHoNa8jaXjq31M) |
| ⚙️ Change server rates | [Watch on YouTube](https://youtu.be/qTEbw1xV3S0?si=zb7n_MQpAz94jET_) |

---

## Quick Start

> [!IMPORTANT]
> The default `config.json` and 1-click installer assume the standard folder layout used by most **Cata / MoP repacks**. You can install anywhere — just edit the paths in `config.json` to point at your repack's executables and config files.
>
> **Recommended layout** (works with default config paths):
> ```
> 📁 YourRepackFolder\
> ├── 📁 Database\
> ├── 📁 Repack\
> └── 📁 wow-server-mcp\   ← clone here
> ```
> ```bash
> cd "C:\path\to\YourRepackFolder"
> git clone https://github.com/timoinglin/wow-server-mcp.git
> ```

### 1. Install & Build

**Easy (Windows):** double-click `install.bat`. It checks for Node.js (installs via `winget` if missing), copies `example.config.json` → `config.json`, runs `npm install`, and builds.

**Manual (any OS):**
```bash
cd wow-server-mcp
cp example.config.json config.json   # Windows: copy example.config.json config.json
npm install
npm run build
```

### 2. Configure

Edit `config.json`:
- **Database credentials** — defaults to `root` / `ascent` on `localhost:3306`
- **RA credentials** — set after creating a GM account (level 3+)
- **Server paths** — only change if your folder layout differs from the recommended one above

### 3. Enable Remote Access (RA) on the Worldserver

In `Repack/worldserver.conf`:
```
Ra.Enable = 1
Ra.IP     = 127.0.0.1
Ra.Port   = 3443
```
Restart the worldserver and put the matching credentials in `config.json` under `remote_access`.

### 4. Add to Your AI Client

Replace `` below with the absolute path to your repack folder.
Use **forward slashes `/`** even on Windows (e.g. `C:/Games/mop_repack/MOPFREE`).

After adding the config, **restart your AI client**; `wow-server` will appear in its tool list.

---

#### 🟠 Claude Desktop

Open **Settings → Developer → Edit Config**, or edit the file directly:

| OS | Path |
|:---|:---|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux   | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "wow-server": {
      "command": "node",
      "args": ["/wow-server-mcp/dist/index.js"]
    }
  }
}
```

If the file already exists, merge the `"wow-server"` entry into the existing `mcpServers` object. Quit Claude from the tray icon (right-click → Quit) before relaunching — closing the window leaves it running in the background.

---

#### 🟢 Claude Code (VS Code extension / CLI)

**Easiest — one command:**

```bash
claude mcp add wow-server -s user -- node "/wow-server-mcp/dist/index.js"
```

`-s user` makes the server available in every project. Use `-s project` to scope it to the current workspace (writes `.mcp.json` to the project root).

**Or edit the project-scoped file by hand**, `/.mcp.json`:

```json
{
  "mcpServers": {
    "wow-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/wow-server-mcp/dist/index.js"]
    }
  }
}
```

Reload VS Code (`Ctrl+Shift+P` → "Developer: Reload Window"). For project-scoped servers, Claude prompts once to approve — click **approve**. Verify with `/mcp` inside Claude Code.

---

#### 🔷 Codex CLI

Add to `~/.codex/config.toml` (create the file if it doesn't exist):

```toml
[mcp_servers.wow-server]
command = "node"
args = ["/wow-server-mcp/dist/index.js"]
```

Start a fresh `codex` session. Tools appear under the namespace `mcp__wow-server__*`.

---

#### 🟣 Antigravity (Google's VS Code-based agent IDE)

**Easiest — built-in UI:** click the **Agent Manager** icon in the top bar, then the **⋯ menu → MCP Servers** and add a new server with:

- **Command:** `node`
- **Args:** `/wow-server-mcp/dist/index.js`

**Or edit the config file directly** at `C:\Users\\.gemini\antigravity\mcp_config.json`:

```json
{
  "mcpServers": {
    "wow-server": {
      "command": "node",
      "args": ["/wow-server-mcp/dist/index.js"],
      "cwd": "/wow-server-mcp"
    }
  }
}
```

---

## Dynamic Schema (Any Expansion)

The MCP ships with the Cata / MoP TrinityCore schema baked in, but it can adapt to any repack — Wrath, Cataclysm, MoP, Legion, AzerothCore variants — by overriding column names.

To set it up for a non-default core:

1. Complete the [Quick Start](#quick-start) so the AI can reach your database.
2. Ask the AI to **run the `discover_schema` tool**. It scans `INFORMATION_SCHEMA` and writes a `schema_override.json` tailored to your DB.
3. The default `example.config.json` already sets `"schemaOverride": "schema_override.json"` — so if you copied that as your `config.json`, the file is picked up on the next start. If your `config.json` doesn't have that line, add it.
4. Restart your AI client. Look for `Schema override loaded from …` in the MCP server's stderr to confirm.

---

## Available Tools (82 total)

### Config Management (4)
| Tool | Description |
|:---|:---|
| `get_config` | Read current config.json |
| `update_config` | Update config fields (deep merge; `config_files` is read-only) |
| `reset_config` | Reset to example defaults |
| `discover_schema` | Auto-detect DB structure for custom repacks |

### Database Access (7)
| Tool | Description |
|:---|:---|
| `db_query` | Parameterized `SELECT` queries |
| `db_insert` | Insert a row |
| `db_update` | Update with `WHERE` |
| `db_delete` | Delete with `WHERE` |
| `db_execute` | Raw SQL (DDL, complex joins, etc.) |
| `db_test_connection` | Test DB connectivity |
| `create_db_backup` | Full or table-specific `mysqldump` with optional `WHERE` |

### RA Commands (2)
| Tool | Description |
|:---|:---|
| `ra_command` | Send a single RA command |
| `ra_command_batch` | Send multiple commands in sequence |

### Process Management (10)
| Tool | Description |
|:---|:---|
| `start_mysql` / `stop_mysql` / `restart_mysql` | MySQL control |
| `start_authserver` / `stop_authserver` / `restart_authserver` | Auth control |
| `start_worldserver` / `stop_worldserver` / `restart_worldserver` | World control |
| `get_server_status` | Check all processes |

### Account Management (7)
| Tool | Description |
|:---|:---|
| `create_account` | Create game account via RA |
| `set_gm_level` | Set GM level (0–9) |
| `set_account_password` | Change password |
| `modify_dp` | Set DP (Battle Pay) balance |
| `add_dp` | Add/subtract DP (atomic) |
| `list_accounts` | List all accounts |
| `get_account_characters` | List characters for an account |

### Server Config Files (5)
| Tool | Description |
|:---|:---|
| `read_server_config` | Read allowed config files |
| `write_server_config` | Write allowed config files |
| `get_conf_value` | Get a single `.conf` setting |
| `update_conf_value` | Update a single `.conf` setting |
| `list_allowed_files` | List which config files are accessible |

### Lookup & Editing (13)
| Tool | Description |
|:---|:---|
| `search_creature_template` / `get_creature_template` / `update_creature_template` | NPC lookup & editing |
| `search_quest_template` / `get_quest_template` / `update_quest_template` | Quest lookup & editing |
| `search_item_template` / `get_item_template` / `update_item_template` | Item lookup & editing |
| `search_gameobject_template` | Gameobject search |
| `get_server_info` | Server uptime/players via RA |
| `get_online_players` | Online players from DB |
| `get_db_stats` | Database statistics |

### NPC Development (13)
| Tool | Description |
|:---|:---|
| `spawn_creature` | Spawn NPC at GM's in-game position via RA |
| `delete_creature_spawn` | Delete a creature spawn by GUID |
| `get_creature_spawns` | List all spawns of a creature entry |
| `clone_creature_template` | Duplicate existing NPC with new entry & name |
| `set_npc_flags` | Set npcflag bitfield (Vendor, QuestGiver, Trainer, etc.) |
| `set_npc_gossip_menu` | Set gossip menu ID on a creature template |
| `search_gossip_menu` | View gossip menu options and text IDs |
| `get_npc_vendor_items` | List items sold by a vendor NPC |
| `add_npc_vendor_item` | Add item to vendor inventory (auto-reloads) |
| `remove_npc_vendor_item` | Remove item from vendor (auto-reloads) |
| `get_waypoints` | List waypoints for a creature path |
| `add_waypoint` | Add waypoint to creature path |
| `delete_waypoints` | Delete all waypoints for a path |

### Quest Development (7)
| Tool | Description |
|:---|:---|
| `create_quest` | Create new quest with title, levels, rewards |
| `delete_quest` | Delete quest and all NPC relations |
| `set_quest_giver` | Assign NPC as quest starter (auto-sets QuestGiver flag) |
| `set_quest_ender` | Assign NPC as quest turn-in (auto-sets QuestGiver flag) |
| `remove_quest_relation` | Remove giver/ender relations |
| `get_quest_relations` | Show all NPCs/GOs that give/finish a quest |
| `get_quest_rewards` | Show reward items, choices, XP, money |

### Loot & World Data (8)
| Tool | Description |
|:---|:---|
| `get_creature_loot` | List loot table for a creature (with item names) |
| `add_creature_loot_item` | Add item to creature loot (chance, qty, quest-only) |
| `remove_creature_loot_item` | Remove item from creature loot |
| `search_loot_by_item` | Find which creatures drop a given item |
| `get_item_loot` | Get loot contents of a container item |
| `search_spell` | Search spells by name or ID from `spell_dbc` |
| `get_world_events` | List world events with active/upcoming status |
| `search_teleport_location` | Find teleport locations by name (with coordinates) |

### Forensics / DB Integrity (6) — new in 1.4.0
| Tool | Description |
|:---|:---|
| `inspect_creature` | One-call deep dive: template (incl. `ScriptName`, `AIName`), quest starter/ender, vendor, smart_scripts summary, spawn count, loot table summary. Flags NPCs whose SmartAI gossip handlers make "missing menu" claims false positives. |
| `inspect_gossip_chain` | Walk a gossip menu: row + options + per-option `action_menu_id` status (exists / missing / GOSSIP_OPTION_* sentinel like `1048576` = battlefield queue) + every NPC using the menu + cross-referenced SmartAI event 62/64 handlers. |
| `get_smart_scripts` | Pull SmartAI rows for any creature / gameobject / quest / etc. with human-readable `event_type` and `action_type` names. |
| `find_orphan_refs` | Generic FK-integrity sweep — "rows in `source.col` pointing to values absent from `target.col`". Auto-excludes gossip sentinels. Pre-built sweep examples in `docs/BUGHUNT.md`. |
| `check_scriptname` | Grep the configured worldserver core source tree (`core_source_path` in `config.json`) for a `ScriptName`. Returns file:line matches or a "not found in upstream — may be in modified core" warning. |
| `inspect_loot_table` | Inspect any loot table for an entry, classifying each row as valid item / currency (negative ID) / reference / missing. Prevents the "chest drops nothing" false positive when 12 of 14 drops actually work. |

See [`docs/BUGHUNT.md`](docs/BUGHUNT.md) for the false-positive playbook these tools were designed around.

---

## Bug-Hunting / DB Integrity

The forensic tools above were built to answer one question: **"is this DB anomaly actually a bug, or does the core handle it some other way?"** Common pitfalls they prevent:

- **Currencies aren't items.** Negative item IDs in loot tables point to `Currency.dbc`, not `item_template`. `inspect_loot_table` labels them explicitly.
- **Magic `action_menu_id` values aren't menus.** `1048576` = `GOSSIP_OPTION_BATTLEFIELD` (Wintergrasp queue), `2097152` = auctioneer, etc. `inspect_gossip_chain` flags all known sentinels.
- **SmartAI bypasses missing gossip rows.** `event_type = 62` (`GOSSIP_SELECT`) fires when a player clicks an option regardle

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [timoinglin](https://github.com/timoinglin)
- **Source:** [timoinglin/wow-server-mcp](https://github.com/timoinglin/wow-server-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-timoinglin-wow-server-mcp
- Seller: https://agentstack.voostack.com/s/timoinglin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.