The 2-Week Minecraft Phase

In December 2025, I found myself in the infamous "2-week Minecraft phase" with my friends. This time, one of my friends was new to Minecraft, and I wanted to make her feel as welcome as possible. Even though we were playing on an always-on server, she only logged on when the rest of us were online — and she told me it was because she didn't want to bother us with gameplay questions while we weren't already all playing.

"How many logs do I need for 14 stairs?", "What do I need to light the portal?", "How do I make a bed?" — these were relatively trivial questions for an experienced player, but not immediately obvious to a new player. They were quite simple, really. I wanted to find a way to help her, but without having to be there all the time. Something that would make her feel comfortable playing at any time, even without us online, and without making her feel disruptive when she inevitably has questions.

The Idea

I had played on private MC servers before, and a lot of them had mods to connect them to Discord — whatever is typed in Minecraft chat is sent to a Discord channel. This gave me an idea: What if I created a Minecraft mod that could act as a two-way bridge between Minecraft chat, and any other service at all? This way, I could connect my Minecraft server to, say, n8n — an automation tool I had been experimenting with recently — and set up an LLM to answer my friend's questions automatically.

It would expose an HTTP endpoint that other applications could send messages to, and it would also send any Minecraft chat messages to another HTTP endpoint. This way, I could set up a webhook in n8n to listen for Minecraft chat messages, and respond accordingly.

The Architecture

Since the server was already running Neoforge, that's what I used. HookRaft is built as a server-side only mod that bridges Minecraft chat with external webhook services. It consists of two main components: an embedded HTTP server that listens for incoming webhook requests, and an outbound HTTP client that forwards Minecraft chat messages to configured endpoints. The mod also includes a chat event handler that listens for Minecraft chat messages and forwards them based on configurable filter modes (e.g., all messages, regex patterns, or command-only mode).

Key Features

• Two-way Communication: Send messages from Minecraft to external services and receive responses back
• Remote Command Execution: Execute Minecraft commands via HTTP with security controls
• Flexible Filtering: Control which messages are forwarded using regex patterns or command-only mode
• In-Game Management: Commands like /hook for sending messages and /hookraft for configuration
• Async Architecture: Non-blocking HTTP operations ensure no performance impact
• Live Configuration: Change settings without server restart

Core Components

InboundWebhookServer: An embedded HTTP server using Java's built-in com.sun.net.httpserver.HttpServer that listens for incoming webhook requests. It exposes three endpoints:

• POST /api/receive - Receives messages from external services and broadcasts them in Minecraft chat
• POST /api/command - Executes Minecraft commands remotely with security filtering
• GET /api/health - Health check endpoint

OutboundWebhookClient: Uses Java 21's java.net.http.HttpClient for non-blocking HTTP requests to external webhooks. It forwards Minecraft chat messages and command invocations to configured endpoints.

ChatEventHandler: Listens to Minecraft's ServerChatEvent and forwards messages based on configurable filter modes (ALL, REGEX, or COMMAND_ONLY). The COMMAND_ONLY mode only forwards messages sent via the /hook command.

Security & Configuration

The mod includes some security features:

• Whitelist/blacklist for remote command execution
• Regex filtering for outbound messages
• All Minecraft interactions execute on the main server thread
• HTTP requests are non-blocking to prevent server lag

Configuration is handled through NeoForge's config system, generating a hookraft-server.toml file with live reloading capabilities.

Usage Example

With n8n automation, I set up a workflow that:

1. Receives chat messages from HookRaft
2. Queries an LLM (Local Ollama server) with Minecraft-specific context
3. If required, the LLM will call tools such as web search, a calculator, or the Hookraft command-running tool.
4. Sends the response back to HookRaft for in-game broadcast

This created an automated help system that could answer my friend's questions even when we weren't online!

Conclusion

HookRaft solved my problem of making Minecraft more accessible for new players. What started as a solution for a friend's gaming experience evolved into a robust, security-conscious mod that could benefit any Minecraft server community. It's now publicly available on CurseForge↗ and my Git server↗. If you're interested in enhancing your Minecraft server with webhook capabilities, give HookRaft a try!