# \ud83e\uddca Minecraft Matrix Chat Bridge<\/p>\n
   <\/p>\n
**A powerful, private, and secure bridge between your Minecraft server and a Matrix homeserver.**<\/p>\n
—<\/p>\n
## \ud83d\udee1\ufe0f Why Matrix?<\/p>\n
In an era where data privacy and user safety are paramount, **Matrix** stands out as the superior choice for gaming communities. Unlike Discord or other centralized platforms, Matrix allows you to:<\/p>\n
* **Own Your Data**: Host your own server. No third party is mining your players’ chat history.
\n* **Ensure Safety**: Create a private, isolated environment perfect for players of all ages. You control who joins and what they see.
\n* **Stay Secure**: Industry-standard encryption and open-source transparency.<\/p>\n
This plugin integrates your Minecraft server directly into this secure ecosystem, providing a seamless experience that feels native to both platforms.<\/p>\n
—<\/p>\n
## \u2728 Key Features<\/p>\n
* **\ud83d\udd04 Two-Way Chat Bridge**
\n * Messages flow instantly between Minecraft and Matrix.
\n * Experience a unified community, whether in-game or on mobile.<\/p>\n
* **\ud83c\udfad True User Impersonation**
\n * Forget generic bot messages!
\n * When a player chats in-game, the message in Matrix appears to come **from their actual account**, complete with their avatar and name.<\/p>\n
* **\ud83d\ude80 Automatic Onboarding & Syncing**
\n * **Auto-Account Creation**: A passwordless Matrix account is automatically created for every player the first time they join.
\n * **Auto-Avatar Sync**: On every join, the plugin checks if the player’s skin has changed and updates their Matrix avatar accordingly.
\n * **Auto-Room Sync**: On every join, players are automatically added to the correct Matrix rooms based on their permissions.<\/p>\n
* **\ud83d\udd10 Role-Based Access**
\n * Automatically manage room memberships based on in-game permissions (e.g., VIPs, Staff).
\n * No need for manual invites; the plugin handles the heavy lifting.<\/p>\n
* **\ud83e\uddf1 Bedrock Player Support**
\n * Differentiate Bedrock players (e.g., from Geyser) by adding a configurable suffix to their Matrix username (e.g., `.Steve` becomes `steve.b`).<\/p>\n
* **\ud83d\udd4a\ufe0f Lightweight & Native**
\n * Built using raw Matrix\/Synapse APIs.
\n * **Zero external dependencies** or bloated libraries.<\/p>\n
—<\/p>\n
## \ud83d\udee0\ufe0f Prerequisites<\/p>\n
* **Minecraft Server**: Spigot, Paper, or Purpur (1.20.6 or newer).
\n* **Matrix Homeserver**: A **Synapse** server where you have Admin access.
\n* **Bot Account**: A Matrix account with **Admin privileges** on your homeserver (required for impersonation and user management).<\/p>\n
—<\/p>\n
## \ud83d\udce5 Installation<\/p>\n
1. **Download** the latest `matrix-chat-1.0.jar` from the releases page.
\n2. **Drop** the jar file into your server’s `plugins` folder.
\n3. **Restart** the server to generate the default configuration file.
\n4. **Configure** `plugins\/MatrixChat\/config.yml` (see below).
\n5. **Important**: Manually invite your bot account to the configured `bridgeRoom` and any other rooms listed in the config. The bot cannot join private rooms automatically without an invite.
\n6. **Reload** or restart to apply changes.<\/p>\n
—<\/p>\n
## \u2699\ufe0f Configuration<\/p>\n
Edit `plugins\/MatrixChat\/config.yml` to connect your worlds.<\/p>\n
“`yaml
\nmatrix:
\n # \ud83c\udf10 Your Matrix homeserver URL
\n homeserver: “https:\/\/chat.yourdomain.com”<\/p>\n
# \ud83e\udd16 The Bot Account
\n # IMPORTANT: Must be a Synapse Admin for impersonation to work.
\n username: “@bot:chat.yourdomain.com”
\n password: “your_secure_password”<\/p>\n
# \ud83c\udf09 The Bridge Room
\n # The main channel where chat is shared. The bot must be a member.
\n bridgeRoom: “!roomid:chat.yourdomain.com”<\/p>\n
# \ud83d\udccf Maximum length of a Matrix message to be bridged to Minecraft.
\n maxMessageLength: 256<\/p>\n
# \ud83e\uddf1 Bedrock Support
\n bedrock:
\n prefix: “.”
\n matrixSuffix: “.b”<\/p>\n
# \ud83d\udce2 Announcements
\n announcements:
\n join: true
\n quit: true
\n death: true
\n firstJoin: true<\/p>\n
# \ud83d\udcc2 Room Management
\n rooms:
\n # Rooms everyone joins automatically
\n default:
\n – “!generalid:chat.yourdomain.com”
\n – “!updatesid:chat.yourdomain.com”<\/p>\n
# \ud83d\udc6e Role-Based Rooms
\n # Map permission nodes to specific rooms
\n roles:
\n mchat.group.staff:
\n – “!staffroomid:chat.yourdomain.com”
\n mchat.group.vip:
\n – “!viproomid:chat.yourdomain.com”
\n“`<\/p>\n
—<\/p>\n
## \ud83d\udcbb Commands & Permissions<\/p>\n
| Command | Permission | Description | —<\/p>\n ## \ud83e\udde0 How It Works<\/p>\n ### The Impersonation Magic ### Echo Prevention —<\/p>\n ## \ud83c\udfd7\ufe0f Building from Source<\/p>\n “`bash —<\/p>\n ## \ud83d\udcc4 License<\/p>\n Distributed under the **MIT License**. See `LICENSE` for more information.<\/p>\n","protected":false},"excerpt":{"rendered":" A powerful, private, and secure bridge between your Minecraft server and a Matrix home server. A self hosted Discord like experience<\/p>\n","protected":false},"featured_media":98740,"template":"","meta":{"_minecraft_slug":"matrix-chat-bridge","_minecraft_project_id":"he7n8Zgo","_minecraft_author":"Sovtoshi","_minecraft_license":"MIT","_minecraft_downloads":25,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"matrix-chat-bridge.zip","_minecraft_size_bytes":52280,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:18:30.568262Z","_minecraft_date_created":"2026-02-19T08:16:22.203997Z","_minecraft_date_modified":"2026-02-18T04:31:28.608311Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/matrix-chat-bridge","_minecraft_icon_attachment_id":98740,"_minecraft_imported_at":"2026-06-05T16:07:09+00:00","_minecraft_import_hash":"fe094e459579f24be4071612adce4b6c","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[127,867,92],"mod_loader":[132],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-98739","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-paper","mod_category-social","mod_category-utility","mod_loader-paper","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n| :— | :— | :— |
\n| `\/mchat register
\n| `\/mchat help` | None | Display the help menu. |<\/p>\n
\nInstead of relaying messages like `[Bot] Player: Hello`, this plugin leverages the **Synapse Admin API**. It obtains a temporary login token for the specific user and sends the message **as them**.
\n* **Result**: A native chat experience.
\n* **Fallback**: If the user isn’t registered, it gracefully falls back to a bot message format.<\/p>\n
\nTo prevent the “infinite loop” of messages repeating themselves, the plugin tags bridged messages with a hidden `[MC]` prefix. The Minecraft listener detects this tag and knows to ignore the message, ensuring a clean chat stream.<\/p>\n
\ngit clone https:\/\/github.com\/yourusername\/matrix-chat.git
\ncd matrix-chat
\nmvn clean package
\n“`<\/p>\n