QueQiao: WebSocket Bridge for Minecraft Servers

What Is QueQiao and Why It Matters for Minecraft Servers

Running a Minecraft server is about more than just blocks and biomes. It is about building a community, keeping players engaged, and sometimes connecting the game world to external tools. QueQiao steps in exactly there. It is a server mod and plugin that bridges the gap between in-game events and outside applications using WebSocket technology. Whether you want to log player actions, trigger Discord messages when someone dies, or send broadcasts from a web dashboard, QueQiao makes it straightforward.

At its core, QueQiao listens to what happens on the server and sends that information out in JSON format. It also accepts incoming JSON messages and forwards them to players. This two-way communication opens up endless possibilities for automation, chat integration, and custom gameplay mechanics. The project is open source under the MIT license and has already attracted a growing ecosystem of community integrations.

Key Features That Set QueQiao Apart

Unlike many plugins that only handle one direction of data, QueQiao works as a real-time event distributor and a command receiver. Here is what it can track and forward from the server:

• Player Chat – every message typed in public chat
• Player Command – any command executed by a player
• Player Death – death events (not available for Velocity proxies)
• Player Join and Quit – login and logout notifications
• Player Advancement – when a player earns an achievement

On the incoming side, you can push messages back into the game using a simple API. The supported message types include:

• Broadcast – send a global chat message to all players
• PrivateMessage – whisper to a specific player
• Title and SubTitle – show large on-screen text
• ActionBar – display text above the hotbar
• Rcon Command – execute server commands remotely

This combination turns your Minecraft server into a fully interactive node that can talk to bots, web panels, and AI agents. The JSON payloads are well-documented, so developers can quickly build custom tools without digging through messy Minecraft internals.

Quick Setup Guide

Getting started with QueQiao is simple, even if you are not a seasoned server admin. The mod supports multiple server platforms, and you can find the appropriate build on Modrinth or CurseForge. After downloading the jar file, place it into your server's mods or plugins folder. Then edit the config.yml file to enable the WebSocket server:

config.yml example:

websocket_server:
  enable: true
  host: "127.0.0.1"
  port: 8080

Once the server starts, QueQiao initializes its WebSocket listener on the specified address and port. You can then connect any API testing tool like ApiFox or a custom integration project. All requests must include the x-self-name header, which must match the server_name in your config. If you set an access_token, the Authorization: Bearer your_token header becomes mandatory.

If you prefer a more visual approach to managing mods, you might appreciate that this mod can be easily installed via the foxygame.net launcher — a convenient, flexible, and modern Minecraft launcher where you can download mods right from the menu without juggling files manually.

Integration Projects and Community Ecosystem

One of the strongest points of QueQiao is its active community. Several popular bot frameworks already have dedicated adapters and plugins built around it. These integrations let you connect Minecraft chat to QQ, Discord, Telegram, and more without writing a single line of code. Some notable projects include:

• NoneBot2 adapter and plugin for Minecraft-to-QQ messaging
• YunZai plugin for chat synchronization
• Koishi plugin for cross-platform message sync
• ZeroBot plugin for automated responses
• AstrBot plugin for interactive bot commands
• Nekro-Agent AI integration for intelligent in-game agents

There is also a separate MCDR (Minecraft Data Relay) implementation called queqiao_mcdr, which provides message exchange capabilities for servers using that framework. If you use the ChatImage mod, QueQiao can work alongside it to display images in chat, further enriching the player experience.

Compatibility and Multi-Version Support

Minecraft updates frequently, and maintaining plugin compatibility can be a headache. QueQiao tackles this with a multi-version build tool developed by the same team. The project uses ModMultiVersion and ModMultiVersionTool to generate artifacts for different Minecraft releases. This means you can often find a version that works with your server, even if it is not the latest. If a specific version is missing, the developers encourage submitting an issue on the project's repository.

Why Use QueQiao Over Traditional Plugins?

Traditional server plugins usually operate in isolation. They might log events to a file or send a simple webhook, but they rarely offer a full bidirectional API. QueQiao treats your Minecraft server as a data source and a message sink simultaneously. This design is ideal for:

• Creating live dashboards that show player activity in real time
• Building custom moderation tools that react to chat patterns
• Integrating with AI chatbots that can respond to player questions
• Automating welcome messages, death announcements, or achievement celebrations

Because everything flows through WebSocket, the connection is persistent and low-latency. You do not need to poll a log file or set up complex event listeners. The JSON structure is clean and predictable, making it easy to parse in any programming language.

Documentation and Getting Help

The official documentation is hosted on ApiFox and covers every endpoint, event payload, and configuration option in detail. It is the best place to learn about advanced features like custom headers, error handling, and authentication. The community Discord server is also active, and you can often get quick answers from other server owners who have already set up similar workflows. If you run into a bug or have a feature idea, the issue tracker on the project's repository is open.

Conclusion

QueQiao transforms a Minecraft server from a closed game environment into an extensible platform. By exposing player events and accepting API calls over WebSocket, it unlocks a world of automation and cross-platform communication. Whether you are a server admin looking to enhance your community or a developer building the next great integration, this mod provides a solid foundation. The growing list of community plugins and the straightforward configuration make it accessible even if you are not deeply technical. With multi-version support and an open-source license, QueQiao is a tool worth adding to your server toolkit.

--- **Update Jul 18, 2026:** Added 1 file for version 26.1.2, 26.1.1, 26.1 (Fabric).