Skip to main content

​
Overview

Proxy servers enable the Minecraft Web Client to connect to Java Minecraft servers using the TCP protocol. The proxy creates a WebSocket connection between your browser and the Minecraft server, bridging the protocol gap without any packet deserialization.
The proxy server simply forwards packets between the client and Minecraft server without processing them. All Minecraft protocol packets are handled directly in your browser.

​
How Proxies Work

When you connect to a server through a proxy:
  1. Your browser establishes a WebSocket connection to the proxy server
  2. The proxy connects to the Minecraft server via TCP
  3. All packets are forwarded in both directions without modification
  4. Your browser processes all Minecraft protocol packets directly
Proxy location affects latency significantly. If both you and the Minecraft server are in Europe, expect ~40ms ping. Cross-continent connections may result in >200ms ping.

​
Self-Hosting a Proxy

​
Quick Start

1

Clone and Install

Clone the repository and install dependencies:
git clone https://github.com/zardoy/minecraft-web-client.git
cd minecraft-web-client
pnpm i
2

Start the Proxy Server

Run the production server:
pnpm prod-start
The proxy will be available at http://localhost:8080
3

Configure the Client

In the web client, specify your proxy server URL in the proxy field:
http://localhost:8080

​
Server Configuration

The proxy server (server.js) accepts several configuration options:

​
Command Line Arguments

node server.js [options] [port]
Available Options:
  • --prod - Run in production mode
  • --log - Enable connection logging
  • --timeout <ms> - Set connection timeout (default: 10000ms)
  • Port number - Specify custom port (default: 8080)
Examples: 
# Production mode on port 8080
node server.js --prod

# Custom port with logging
node server.js --log 3000

# Custom timeout (20 seconds)
node server.js --timeout 20000

​
Environment Variables

# Production mode
NODE_ENV=production

# Connection timeout in milliseconds
TIMEOUT=15000

# Enable connection logging
LOG=true

​
Configuration File

The proxy reads from config.json to set defaults: 
{
  "defaultProxy": "https://proxy.mcraft.fun",
  "defaultHost": "<from-proxy>"
}
For custom deployments, you can override settings in public/config.json: 
{
  "defaultProxy": ""
}
Setting defaultProxy to an empty string tells the client to use the current server URL as the proxy.

​
Cloud Deployment

​
Deploy to Koyeb

Click the button below for one-click deployment: Deploy to Koyeb

​
Other Platforms

The proxy can be deployed to any platform supporting Node.js or Docker:
  • Heroku: Use the included Dockerfile.proxy
  • Railway: Connect your GitHub repository
  • Vercel: Limited support (WebSocket restrictions)
  • VPS: Any Linux server with Node.js 18+
# Install Node.js 18+ and pnpm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g pnpm

# Clone and build
git clone https://github.com/zardoy/minecraft-web-client.git
cd minecraft-web-client
pnpm i
pnpm build

# Run with PM2 (process manager)
npm install -g pm2
pm2 start server.js --name mc-proxy -- --prod
pm2 save
pm2 startup

​
mwc-proxy: Standalone Proxy

For making your own Minecraft server accessible to web clients, use mwc-proxy - a lightweight WebSocket proxy.

​
Features

  • Runs alongside your Minecraft server
  • Minimal resource usage
  • Direct connections via wss://play.example.com
  • Automatic client detection via ?client_mcraft URL parameter

​
Installation

git clone https://github.com/zardoy/mwc-proxy.git
cd mwc-proxy
npm install

​
Configuration

// config.js
module.exports = {
  port: 8080,
  minecraftServer: {
    host: 'localhost',
    port: 25565
  }
}

​
Running

node index.js
Players can now connect to your server using: 
wss://play.example.com?client_mcraft

​
CORS Configuration

For proper proxy operation, ensure CORS headers are configured: 
const cors = require('cors')
app.use(cors())
The default configuration allows all origins (allowOrigin: '*').

​
Monitoring and Logs

Enable logging to monitor connections: 
node server.js --log
This will log:
  • New WebSocket connections
  • Minecraft server connections
  • Connection errors and timeouts
  • Disconnections

​
Troubleshooting

Increase the timeout value if connecting to distant servers:
node server.js --timeout 30000
Ensure your proxy has CORS enabled and accepts requests from your web client domain.
Use a proxy server geographically close to both you and the Minecraft server for best performance.
  • Check firewall rules allow outbound WebSocket connections
  • Verify the proxy server is running and accessible
  • Ensure you’re using the correct protocol (ws:// or wss://)

​
Security Considerations

Production Deployments:
  • Use HTTPS/WSS connections in production
  • Implement rate limiting to prevent abuse
  • Consider authentication for private proxies
  • Monitor resource usage to prevent DoS attacks

​
Rate Limiting Example

const rateLimit = require('express-rate-limit')

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
})

app.use(limiter)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us