Overview
Minecraft Web Client can connect to almost any Minecraft Java Edition server running versions 1.8 through 1.21.5. Since browsers can’t directly connect via TCP, the client uses WebSocket proxy servers to bridge the connection.The proxy server acts as a transparent relay - all Minecraft protocol packets are processed directly in your browser without deserialization on the proxy.
Quick Connect
Connect to a server using query parameters:Connection Parameters
Server address (with optional port)Examples:
play.example.commc.server.net:25565192.168.1.100:25566
Minecraft version to use for connectionDefault: Auto-detected or 1.19.4
Proxy server address to useDefault: Built-in proxy server
Player username (offline mode)
Server name for saving to server list
Proxy Servers
Proxy servers enable browser clients to connect to Minecraft servers by converting TCP connections to WebSockets.How Proxies Work
The connection flow looks like this:All Minecraft protocol packets are processed in your browser. The proxy only forwards encrypted data without inspecting it.
Built-in Proxy
The project provides free public proxy servers:- Default proxy available at the hosted domains
- Handles connections for both online and offline mode servers
- Supports Microsoft authentication for online mode
Custom Proxy Setup
For the best performance, host your own proxy server:Install Dependencies
See CONTRIBUTING.md for setup details
Docker Proxy Deployment
Deploy a standalone proxy using Docker:Deploy to Cloud
One-click deploy to Koyeb cloud platform
Server-Side Proxy (mwc-proxy)
For server owners, use mwc-proxy to allow direct WebSocket connections:- Runs alongside your Minecraft server
- Eliminates third-party proxy dependency
- Players connect via
wss://play.example.com
Online Mode Authentication
Connect to online mode servers using Microsoft account authentication.Requirements
Authentication Flow
Microsoft Sign-In
You’ll be prompted to authenticate with Microsoft:
- A device code will be displayed
- Visit the authentication URL
- Enter the code and sign in
Token Caching
Authentication tokens are cached in your browser:
- Future connections use cached tokens
- No need to re-authenticate until tokens expire
Proxy Authentication Support
The proxy must expose authentication endpoints:If the proxy doesn’t support authentication, you’ll see: “Selected proxy server does not support Microsoft authentication”
Server Address Parsing
The client supports multiple server address formats:- Standard
- With Version
- WebSocket
- IP Address
Connection Options
Auto-Connect
Enable automatic connection for embedded iframes:Lock Connect Screen
Disable input fields in connect screen (for embedded use):- Server address
- Version
- Proxy settings
- Username
Add Artificial Latency
Test high-ping scenarios:Offline Mode vs Online Mode
Offline Mode
- No authentication required
- Any username allowed
- Common on cracked servers
- No Microsoft account needed
Online Mode
- Microsoft authentication required
- Verified Minecraft account
- Official servers and most public servers
- Secure player identity
Supported Versions
Server versions 1.8 - 1.21.5 are supported through the Mineflayer library.First-class tested versions: 1.19.4 and 1.21.4Versions below 1.13 may have limited functionality.
Network Performance
Expected Latency
Client, proxy, and server all in the same region (e.g., all in Europe)
Using residential IP proxy services
Client in US, proxy in Europe, server in US (transatlantic double trip)
For best performance, host your own proxy in the same region as the server you’re connecting to.
Troubleshooting
Connection Timeout
Connection Timeout
Cause: Proxy server unreachable or server is downSolutions:
- Verify the server address is correct
- Try a different proxy server
- Check if the Minecraft server is online
Proxy Authentication Failed
Proxy Authentication Failed
Cause: Proxy doesn’t support Microsoft authenticationSolutions:
- Use the default built-in proxy
- Update your custom proxy to latest version
- Check proxy capabilities at
/api/vm/net/connect
Kicked by Server
Kicked by Server
Cause: Online mode server rejecting connectionSolutions:
- Ensure you’re authenticated with Microsoft account
- Verify your Minecraft license is valid
- Check server version compatibility
High Ping / Lag
High Ping / Lag
Cause: Proxy server far from Minecraft serverSolutions:
- Host your own proxy closer to the server
- Choose a proxy in the server’s region
- Check your internet connection speed
