MC Matrix Bridge

MC Matrix Bridge

A forge mod that bridges chat between a Minecraft server and a matrix room.

753 downloads 0 followers

Minecraft Matrix Bridge (Forge/NeoForge, Server-Only)

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).
  • The "Matrix room connected: …" notice is localized server-side based on each player's reported client language (currently includes en_us and zh_cn).
  • If the bot is invited to the configured room but not joined yet, it will auto-accept the invite and join on startup.
  • Event Taps: dynamically subscribe to Forge/NeoForge events and forward them to Matrix for debugging/monitoring.

Requirements

  • Java 17 (Forge 1.18–1.20), Java 21 (Forge/NeoForge 1.21.x), or Java 25 (Forge/NeoForge 26.1)
  • Minecraft Forge/NeoForge 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
    • 26.1
  • Matrix room must be unencrypted (no E2EE)

Installation

  1. Download the jar or build it locally with ./scripts/build_dist.sh (all supported versions) or ./scripts/build_dist_26.sh (26.x only). The generated jars are written to dist/.
  2. Drop the jar into your Forge/NeoForge server's mods/ folder (pick the jar matching your loader + Minecraft major).
  3. Start the server once to generate config.

Build all versions (creates dist/)

To build jars for all supported Minecraft versions and collect them into dist/:

  • ./scripts/build_dist.sh

dist/ includes Forge jars for 1.18.x–1.21.x and 26.x, plus NeoForge jars for 1.21.x and 26.x.

Build only the 26.x line

The 26.x projects use the dedicated Gradle 9 wrapper and are conditionally included by settings.gradle.

  • Build and collect both 26.x jars into dist/: ./scripts/build_dist_26.sh
  • Build Forge 26 only: ./gradlew-26 -Pomx_modern_26=true :forge-26:build
  • Build NeoForge 26 only: ./gradlew-26 -Pomx_modern_26=true :neoforge-26:build
  • On Windows, use gradlew-26.bat instead of ./gradlew-26

./scripts/build_dist_26.sh produces:

  • dist/minecraftmatrixbridge-forge-26.x-<version>.jar
  • dist/minecraftmatrixbridge-neoforge-26.x-<version>.jar
  • dist/SHA256SUMS.txt

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)

Bridge Options

  • bridge.enableMcToMatrix (default true) - Forward MC chat to Matrix
  • bridge.enableMatrixToMc (default true) - Forward Matrix messages to MC
  • bridge.announceConnected (default true) - Announce Matrix room connected: {roomIdOrAlias} when bridge starts
  • bridge.enableJoinLeaveToMatrix (default false) - Send {player} joined/left the game to Matrix
  • bridge.enableServerLifecycleToMatrix (default false) - Send Server started/stopping to Matrix
  • bridge.mcToMatrixPrefix (default [MC] ) - Prefix for MC messages in Matrix
  • bridge.matrixToMcPrefix (default [Matrix] ) - Prefix for Matrix messages in MC
  • bridge.matrixBotPrefix (default !mc) - Matrix bot command prefix; messages starting with this prefix are treated as bot commands and are not forwarded to Minecraft chat
  • bridge.syncTimeoutMs (default 30000) - Matrix sync timeout in milliseconds
  • bridge.timelineLimit (default 20) - Maximum timeline events per sync
  • bridge.maxQueueSize (default 1000) - Maximum outgoing message queue size
  • bridge.dedupSize (default 512) - Event deduplication cache size

Event Tap Options

  • bridge.enableEventTaps (default true) - Enable or disable event taps feature entirely. When disabled, no event indexing occurs at startup.
  • bridge.maxActiveEventTaps (default 10) - Maximum concurrent event subscriptions
  • bridge.defaultEventThrottleMs (default 1000) - Minimum interval between forwarded events (prevents spam)
  • bridge.eventCommandMinPowerLevel (default 50) - Minimum Matrix power level required to use event commands from Matrix (0=default user, 50=moderator, 100=admin)

World-save state

Sync state is stored at:

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

Commands

Minecraft Commands (OP-only)

  • /matrix status - Show bridge status
  • /matrix reload - Reload bridge config
  • /matrix test - Send a test message to Matrix

Matrix Bot Commands

Matrix room bot commands (requires bridge.enableMatrixToMc=true):

  • !mc help (or replace !mc with bridge.matrixBotPrefix)
  • !mc list - Replies with online player names; command messages are not forwarded into Minecraft chat

Event Taps (Advanced)

Event taps allow server operators to subscribe to Forge/NeoForge events at runtime and forward them to the Matrix room. This is useful for debugging and monitoring.

Minecraft Commands (OP-only)

  • /matrix event on <eventName> [filter] [duration] - Enable event tap
    • eventName: Simple class name (e.g., ServerChatEvent) or fully-qualified class name
    • filter: Optional substring filter (case-insensitive)
    • duration: once (default), permanent, or time-based (30s, 10m, 2h, 1d)
  • /matrix event off <eventName> - Disable event tap
  • /matrix event list - List active event taps
  • /matrix event search <query> - Search available events
  • /matrix event help - Show help

Matrix Bot Commands

Same commands available via Matrix (requires bridge.enableMatrixToMc=true and bridge.enableEventTaps=true):

  • !mc event on <eventName> [filter] [duration]
  • !mc event off <eventName>
  • !mc event list
  • !mc event search <query>
  • !mc event help

Matrix event commands require the sender to have a power level >= bridge.eventCommandMinPowerLevel (default 50).

Safety Features

  • Master switch (enableEventTaps) - Disable entirely to skip event indexing at startup
  • Maximum 10 concurrent event taps (configurable)
  • Default 1-second throttle between forwarded events
  • Tick events automatically enforce minimum 1-second throttle
  • Event output truncated to 2048 characters
  • Client-only events are rejected on dedicated servers

Examples

# Monitor all chat events (fire once)
/matrix event on ServerChatEvent

# Monitor player logins for 10 minutes
/matrix event on PlayerLoggedInEvent "" 10m

# Monitor block breaks with "diamond" in the event data, permanently
/matrix event on BlockEvent diamond permanent

# From Matrix
!mc event on ServerChatEvent
!mc event list
!mc event off ServerChatEvent

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.

Version Minecraft Loader Download

0.1.6 (neoforge 26.1.x)

0.1.6

26.1, 26.1.1, 26.1.2
neoforge
Download

0.1.6 (forge 1.19.x)

0.1.6

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.6 (forge 1.18.x)

0.1.6

1.18, 1.18.1, 1.18.2
forge
Download

0.1.6 (forge 26.1.x)

0.1.6

26.1, 26.1.1, 26.1.2
forge
Download

0.1.6 (neoforge 1.21.x)

0.1.6

1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9, 1.21.10, 1.21.11
neoforge
Download

0.1.6 (forge 1.21.x)

0.1.6

1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9, 1.21.10, 1.21.11
forge
Download

0.1.6 (neoforge 26.2.x)

0.1.6

26.2
neoforge
Download

0.1.6 (forge 1.20.x)

0.1.6

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4, 1.20.5, 1.20.6
forge
Download

0.1.6 (forge 26.2.x)

0.1.6

26.2
forge
Download

0.1.5 (neoforge 26.1.x)

0.1.5

26.1, 26.1.1, 26.1.2
neoforge
Download

0.1.5 (forge 1.20.x)

0.1.5

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4, 1.20.5, 1.20.6
forge
Download

0.1.5 (forge 26.2.x)

0.1.5

26.2
forge
Download

0.1.5 (neoforge 1.21.x)

0.1.5

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
neoforge
Download

0.1.5 (forge 1.21.x)

0.1.5

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download

0.1.5 (forge 1.18.x)

0.1.5

1.18, 1.18.1, 1.18.2
forge
Download

0.1.5 (neoforge 26.2.x)

0.1.5

26.2
neoforge
Download

0.1.5 (forge 26.1.x)

0.1.5

26.1, 26.1.1, 26.1.2
forge
Download

0.1.5 (forge 1.19.x)

0.1.5

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.4

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
neoforge
Download

0.1.4

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download

0.1.4

1.18, 1.18.1, 1.18.2
forge
Download

0.1.4

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4
forge
Download

0.1.4

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.4

26.1, 26.1.1, 26.1.2
forge
Download

0.1.4

26.1, 26.1.1, 26.1.2
neoforge
Download

0.1.3

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4
forge
Download

0.1.3

1.18, 1.18.1, 1.18.2
forge
Download

0.1.3

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download

0.1.3

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.3

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
neoforge
Download

0.1.2

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download

0.1.2

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.2

1.18, 1.18.1, 1.18.2
forge
Download

0.1.2

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
neoforge
Download

0.1.2

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4
forge
Download

0.1.1

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download

0.1.1

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4
forge
Download

0.1.1

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.1

1.18, 1.18.1, 1.18.2
forge
Download

0.1.0

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download

0.1.0

1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4
forge
Download

0.1.0

1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4
forge
Download

0.1.0

1.21, 1.21.1, 1.21.10, 1.21.11, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9
forge
Download