Skip to main content

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:
https://mcraft.fun/?ip=hypixel.net&version=1.19.4

Connection Parameters

ip
string
required
Server address (with optional port)Examples:
  • play.example.com
  • mc.server.net:25565
  • 192.168.1.100:25566
version
string
Minecraft version to use for connectionDefault: Auto-detected or 1.19.4
proxy
string
Proxy server address to useDefault: Built-in proxy server
username
string
Player username (offline mode)
name
string
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
Public proxies may have higher latency (200ms+) depending on your location and the server location.

Custom Proxy Setup

For the best performance, host your own proxy server:
1

Clone Repository

git clone https://github.com/zardoy/minecraft-web-client.git
cd minecraft-web-client
2

Install Dependencies

pnpm install
See CONTRIBUTING.md for setup details
3

Start Proxy Server

pnpm prod-start
The proxy will run on port 8080 by default.
4

Connect to Your Proxy

https://mcraft.fun/?proxy=http://localhost:8080

Docker Proxy Deployment

Deploy a standalone proxy using Docker:
docker build . -f Dockerfile.proxy -t minecraft-web-proxy
docker run -p 8080:8080 minecraft-web-proxy

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
// The client adds ?client_mcraft to identify itself
// From src/customChannels.ts
const isWebSocketServer = (server) => {
  return server.startsWith('ws://') || server.startsWith('wss://')
}

Online Mode Authentication

Connect to online mode servers using Microsoft account authentication.

Requirements

Online mode authentication requires:
  • A proxy server that supports authentication endpoints
  • Microsoft account with Minecraft Java Edition license
  • HTTPS connection (Crypto API requirement)

Authentication Flow

1

Select Server

Choose an online mode server and ensure you’re using a compatible proxy.
2

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
3

Token Caching

Authentication tokens are cached in your browser:
  • Future connections use cached tokens
  • No need to re-authenticate until tokens expire
4

Join Server

The client handles session server validation automatically.
// Authentication implementation from src/microsoftAuthflow.ts
const authFlow = {
  async getMinecraftJavaToken () {
    setProgressText('Authenticating with Microsoft account')
    
    await fetch(authEndpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        ...tokenCaches,
        connectingServer,
        connectingServerVersion
      }),
    })
  }
}

Proxy Authentication Support

The proxy must expose authentication endpoints:
// From src/microsoftAuthflow.ts:20
export const getProxyDetails = async (proxyBaseUrl: string) => {
  const url = `${proxyBaseUrl}/api/vm/net/connect`
  const result = await fetch(url)
  const json = await result.json()
  
  // Check for auth capabilities
  authEndpoint = json.capabilities.authEndpoint
  sessionEndpoint = json.capabilities.sessionEndpoint
}
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:
play.example.com
mc.server.net:25565
// Address parsing from src/parseServerAddress.ts
export const parseServerAddress = (address: string): ParsedServerAddress => {
  // Handle ws:// and wss:// WebSocket addresses
  if (/^ws:[^/]/.test(address)) address = address.replace('ws:', 'ws://')
  if (/^wss:[^/]/.test(address)) address = address.replace('wss:', 'wss://')
  const isWebSocket = address.startsWith('ws://') || address.startsWith('wss://')
  
  // Parse port and version from address
  // Format: host:port:version or host:version:port
}

Connection Options

Auto-Connect

Enable automatic connection for embedded iframes:
?ip=server.com&version=1.19.4&autoConnect=true
Auto-connect must be enabled in config.json (allowAutoConnect: true)

Lock Connect Screen

Disable input fields in connect screen (for embedded use):
?ip=server.com&version=1.19.4&lockConnect=true
This prevents users from changing:
  • Server address
  • Version
  • Proxy settings
  • Username

Add Artificial Latency

Test high-ping scenarios:
?addPing=100
Adds 100ms to both directions (total +200ms to your ping).

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
// Offline mode example from src/packetsReplay/replayPackets.ts
serverOptions: {
  'online-mode': false,
  // ...
}

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

Best Case
~40ms
Client, proxy, and server all in the same region (e.g., all in Europe)
Residential Proxy
~180ms
Using residential IP proxy services
Worst Case
200ms+
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

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
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
Cause: Online mode server rejecting connectionSolutions:
  • Ensure you’re authenticated with Microsoft account
  • Verify your Minecraft license is valid
  • Check server version compatibility
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

Advanced Configuration

Query Parameter Reference

See Query Parameters for the complete list of connection options.

Custom Channels

Enable WebSocket-based custom protocol channels:
// From src/defaultOptions.ts
customChannels: 'websocket'
This enables custom block models and other protocol extensions.

Build docs developers (and LLMs) love