MC Matrix Bridge

Minecraft Matrix Bridge

Bridges chat between a Minecraft server and one Matrix room (unencrypted only).

Features

• MC → Matrix: forwards player chat into a Matrix room.
• Matrix → MC: forwards Matrix m.text room messages into Minecraft server chat.
• Server-only: vanilla clients can join without installing anything (no client mod).
• Sync state stored in the world save (prevents replay spam on restart).
• If the bot is invited to the configured room but not joined yet, it will auto-accept the invite and join on startup.

Requirements

• Java 17 (Forge 1.18–1.20) or Java 21 (Forge 1.21+)
• Minecraft Forge server matching the versions. I only manually test it in popular minor versions, and hopefully it works in other minor versions.
  • 1.18.2
  • 1.19.2
  • 1.20.1
  • 1.21.1
• Matrix room must be unencrypted (no E2EE)

Installation

1. Download the jar.
2. Drop the jar into your Forge server’s mods/ folder.
3. Start the server once to generate config.

Configuration

Edit config/minecraftmatrixbridge.toml:

• matrix.homeserver (required) e.g. https://matrix.example.com
• matrix.roomId (required) room ID !abcdef:example.com or room alias #myroom:example.com (the room should not be encrypted)
• matrix.accessToken (required, or use env variable MATRIX_ACCESS_TOKEN)

Optional:

• bridge.enableMcToMatrix (default true)
• bridge.enableMatrixToMc (default true)
• bridge.announceConnected (default true) announces Matrix room connected: {roomIdOrAlias}
• bridge.enableJoinLeaveToMatrix (default false) sends {player} joined/left the game to Matrix
• bridge.enableServerLifecycleToMatrix (default false) sends Server started/stopping to Matrix
• bridge.mcToMatrixPrefix (default [MC])
• bridge.matrixToMcPrefix (default [Matrix])
• bridge.syncTimeoutMs (default 30000)
• bridge.timelineLimit (default 20)
• bridge.maxQueueSize (default 1000)
• bridge.dedupSize (default 512)

World-save state

Sync state is stored at:

• <world>/data/minecraftmatrixbridge/state.json

Commands

OP-only:

• /matrix status: show bridge status
• /matrix reload: reload bridge config
• /matrix test: send a test message to Matrix

Acknowledgments

I appreciate the great mod projects (e.g. Matrix Bridge) that have inspired me to create this project.

License

The mod is licensed under the AGPL-3.0 license.