Skip to main content

Simple Telnet library optimized for the MUD subset of Telnet.

Project description

Volund's MudTelnet library for Python


Name: Volund



Discord: Volund#1206

Discord Channel:


Home Repository:


MIT license. In short: go nuts, but give credit where credit is due.

Please see the included LICENSE.txt for the legalese.


MUD (Multi-User Dungeon) games and their brethren like MUSH, MUX, MUCK, and MOO (look 'em up!) utilize a peculiar subset of telnet. At least, SOME do - there are servers and clients which don't bother with telnet negotiation. But, for those that do, the telnet features largely begin and end with using IAC WILL/WONT/DO/DONT Negotiation and IAC SB IAC SE to send arbitrary data. In a way, MUD Telnet has diverged to become its own dialect. Library support for MUD-specific features like MXP, MSSP, and MCCP2 can be hard to come by. This library attempts to provide a one-stop-shop for handling MUD Telnet.

This library isn't a MUD. It doesn't open any ports or send data. It's simply a tool for taking the bytes a program would receive from a client and turning it into a series of 'events' that user-given application logic can then utilize, and a way to encode 'outgoing events' into bytes to be sent back to a client.


  • MCCP2 (Mud Client Compression Protocol v2)
  • MTTS (Mud Terminal Type Standard, aka TTYPE)
  • NAWS (Negotiate About Window Size)
  • Suppress_GA
  • Linemode
  • MSSP (Mud Server Status Protocol)
  • MXP (Mud eXtension Protocol)


  • MCCP3 (Mud Client Compression Protocol v3)
  • MUD Prompt support
  • GMCP (Generic Mud Communication Protocol)
  • MSDP (Mud Server Data Protocol)
  • MNES (Mud New-Environ Standard)


Glad you asked.

Input from clients must be converted to TelnetFrame, first.

from mudtelnet import TelnetFrame
data = bytearray([255, 251, 31, 13])
frame, size = TelnetFrame.parse(data)

You'll notice that frame is a NEGOTIATION type. size is 3. data was read but not modified. in order to consume bytes, you would need to del data[:size] after verifying that a frame was parsed - if there wasn't enough bytes, then frame will be None.

Each client session needs an associated TelnetConnection object.

from mudtelnet import TelnetConnection

conn = TelnetConnection()

out_buffer = bytearray()
out_events = list()
changed = conn.process_frame(frame, out_buffer, out_events)

Once you have a frame, you feed it to TelnetConnection.process_frame(). This method accepts a bytearray to append outgoing bytes to (as certain input will result in immediate output, such as option negotiation) and also a list that protocol events (such as user commands) will be appended to. It returns a dictionary of what CHANGED, if anything - such as if MCCP2 was enabled or the client's name was identified via MTTS.

To send data...

from mudtelnet import TelnetOutMessage, TelnetOutMessageType

msg = TelnetOutMessage(TelnetOutMessageType.LINE, "Mud Telnet makes it easy!")

conn.process_out_message(msg, out_buffer)

The message will be encoded to bytes, which are then appended to out_buffer.


Q: This is cool! How can I help?
A: Patreon support is always welcome. If you can code and have cool ideas or bug fixes, feel free to fork, edit, and pull request! Join our discord to really get cranking away though.

Q: I found a bug! What do I do?
A: Post it on this GitHub's Issues tracker. I'll see what I can do when I have time. ... or you can try to fix it yourself and submit a Pull Request. That's cool too.

Q: But... I want a MUD! Where do I start making a MUD?
A: Coming soon...

Q: Why not just feed data straight to TelnetConnection? Why manually create TelnetFrames first?
A: Eventually, I want to add MCCP3 support, which would call for decompressing incoming data. Since the client will send data to trigger the server understanding that all following data will be compressed, Frames must be parsed one at a time so that any remaining data can be optionally decompressed. It's easy to create a 'BufferedTelnetConnection' subclass that handles all of this for you, though.

Special Thanks

  • The Evennia Project.
  • All of my Patrons on Patreon.
  • Anyone who contributes to this project or my other ones.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mudtelnet-0.8.0.tar.gz (11.9 kB view hashes)

Uploaded source

Built Distribution

mudtelnet-0.8.0-py3-none-any.whl (14.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page