Getting started with MUD Client

Posted by Kyle Hankinson November 12th, 2026

MUD Client is a free MUD client for macOS and Windows. This guide takes you from a fresh install to a connected world with your first trigger and alias. Everything here works the same on both platforms unless it says otherwise.

Install

Get MUD Client from the Mac App Store or the Microsoft Store (Windows 10 version 2004 or later, or Windows 11). The stores keep it up to date.

The world picker

When no world is open, MUD Client shows the world picker: a grid of your worlds with Edit, Delete and Connect buttons and a search box. Double-click a world, or select it and press Return, to connect. On Windows the first launch adds a ready-made world for Lost Wishes, with triggers, a status bar and a map already set up, so you can see what a finished world looks like.

Add a world

Click New Connection and fill in:

  • Title - the name shown in the picker.
  • Server address and Server port - from your game's website. New worlds start on port 23.
  • User and Password - optional. If you fill in User, MUD Client sends your name and then your password just after connecting, so you log in automatically. The password is masked on screen.
  • Automatically reconnect - tries again with a countdown if the connection drops.

The Advanced menu has Enable GMCP and Enable MCCP2 (both worth leaving on), local echo, clearing the input after sending, and a Login Script that runs each time you connect.

Connect and disconnect

Connect from the picker. On a Mac you can also use File > Connect or the Connect menu, which lists every world; on Windows, File > Connections (Ctrl+O). To leave, type #disconnect, or close the window. Windows also has File > Disconnect and Reconnect, and both platforms have a reconnect button beside the input box.

Typing commands

  • Up and Down step through the commands you have sent.
  • Tab completes words the game has shown you, and your alias names. Press it again to cycle through the matches.
  • ; separates several commands on one line: get all from corpse;bury corpse.
  • Lines starting with # are commands for the client, such as #reload. The console commands post lists them all.

Your first alias

Open the Scripting window with the Aliases button in the toolbar (on Windows also Tools > Scripting). The window has tabs for Notes, Aliases, Triggers, Scripts and UI, and on Windows a Timers tab as well.

Click + to add an alias. Give it a name, set the pattern to gp, keep the type as Begins with, and set the action to:

command('get all from corpse');
command('put coins in pack');

Click Save & Close, type gp, and both commands go to the game. Actions are JavaScript, so an alias can do anything a short script can.

Your first trigger

Switch to the Triggers tab and click +. Triggers watch the text from the game. Try one that answers when someone greets you:

  • Pattern type: Regex
  • Match string: ^(\w+) waves happily at you\.$
  • Action: command('wave \1');

\1 is the first capture group, here the name of whoever waved. MUD Client puts the captured text into the action before it runs, so it goes inside the quotes. The trigger editor tests your pattern against a line as you type, so you can check it before saving. The regular expression tips cover patterns in more depth.

Triggers can also fire on GMCP data instead of text: choose the Variable updated type and enter a GMCP path such as Char.Vitals.hp. The GMCP triggers post shows how.

Notes, scripts and timers

  • Notes are plain text kept with the world, handy for quest steps or directions.
  • Scripts hold JavaScript you want to share between triggers and aliases; see the Scripts post.
  • Timers start from a script with startTimer, and #timers lists the ones running.
  • Variables set with setVar are listed by #vars, and #set NAME=VALUE changes one from the command line.

Where your world is saved

Each world is a folder named after it, ending in .mud, holding its connection settings, triggers, aliases, notes, scripts and map. On a Mac the worlds live in iCloud Drive's Documents folder when iCloud is available, otherwise in Documents; on Windows they are in %LOCALAPPDATA%\MudClient. The format is the same on both platforms, so a world made on one opens unchanged on the other. To share worlds between computers, point Settings > General > Worlds folder at a shared folder on each.

You can also move just the scripting between worlds: Export Configuration in the Scripting window saves triggers, aliases, notes, scripts and UI to one file, without your login details, and Import Configuration loads it.

Next steps

Tags: General