mineconnect 0.1.1

Minecraft TCP/UDP to WebSocket bridge with Cloudflare tunnel support

MineConnect

Minecraft TCP/UDP to WebSocket bridge with Cloudflare tunnel support

A Python module for bridging Minecraft Java and Bedrock connections through WebSocket to Cloudflare tunnels, enabling secure remote access to your local Minecraft servers.

Features

• 🎮 Dual Support: Both Minecraft Java Edition and Bedrock Edition
• 🔒 Secure Tunnels: Uses Cloudflare tunnels for encrypted connections
• 🚀 Simple API: Just a few lines of code to get started
• ⚙️ Configurable: Customize ports and tunnel modes
• 📊 Real-time Logs: See connection status and activity
• 🔧 Easy Setup: One-time tunnel configuration
• 💻 Client Included: Connect from anywhere with CLI or GUI

Components

Server (Host your Minecraft server)

Run the server-side to bridge your local Minecraft servers to Cloudflare tunnels.

Client (Connect to servers)

Connect to MineConnect servers from anywhere:

• GUI Mode: Web interface with buttons
• CLI Mode: Interactive command-line interface
• Daemon Mode: Run in background
• Python API: Integrate into your code

Installation

From Source (Development)

cd c:\Projects\MineConnect\server
pip install -e .

From PyPI (Future)

pip install mineconnect

One-Time Setup

Before using MineConnect, run the tunnel setup (requires cloudflared installed):

mineconnect-setup

Or:

python -m mineconnect.tunnel_setup

This will:

1. Authenticate with Cloudflare
2. Create two tunnels (java and bedrock)
3. Configure DNS routing
4. Update configuration files

Usage

Simple API

from mineconnect import mcs

# Use default ports (25565 for Java, 19132 for Bedrock)
session = mcs.config()
session.start()

Custom Ports

from mineconnect import mcs

# Custom Minecraft server ports
session = mcs.config(tcp_port=25566, udp_port=19133)
session.start()

Single Tunnel Mode

from mineconnect import mcs

# Use one tunnel with two ingress rules instead of two separate tunnels
session = mcs.config(tcp_port=25565, udp_port=19132, single_tunnel=True)
session.start()

Full Example

from mineconnect import mcs

def main():
    # Configure server with custom ports
    session = mcs.config(
        tcp_port=25565,      # Minecraft Java Edition port
        udp_port=19132,      # Geyser/Bedrock port
        single_tunnel=False  # Use two separate tunnels
    )
    
    # Start server - blocks and shows logs until Ctrl+C
    try:
        session.start()
    except KeyboardInterrupt:
        print("Server stopped by user")

if __name__ == "__main__":
    main()

Client Usage

GUI Mode (Easiest)

mineconnect-gui

Opens a web interface at http://localhost:8080

Interactive CLI

mineconnect-client

Interactive commands: connect, disconnect, status, quit

Daemon Mode

# Connect both tunnels
mineconnect-client --both

# Connect Java only
mineconnect-client --java

# Custom domain
mineconnect-client --both --domain yourdomain.com

Python API (Client)

from mineconnect.client import MineConnectClient

# Create client
client = MineConnectClient(domain="ideadev.me")

# Connect to server
client.connect_both()  # or connect_java() / connect_bedrock()

# ... play Minecraft on localhost:25565 or localhost:19132 ...

# Disconnect
client.disconnect()

See CLIENT_GUIDE.md for complete client documentation.

Parameters

Server API

mcs.config(tcp_port, udp_port, single_tunnel)

• tcp_port (int, default: 25565): Port where your Minecraft Java Edition server is running
• udp_port (int, default: 19132): Port where your Geyser/Bedrock server is running
• single_tunnel (bool, default: False): Use single tunnel with two ingress rules instead of two separate tunnels

session.start()

Starts all services:

• TCP WebSocket bridge (port 8764)
• UDP WebSocket bridge (port 8765)
• Cloudflared tunnel(s)

Logs are displayed in real-time. Press Ctrl+C to stop all services gracefully.

Prerequisites

1. Python 3.8+
2. cloudflared: Install from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/
3. Minecraft Java Server: Running on specified tcp_port (default: localhost:25565)
4. Geyser (for Bedrock support): Running on specified udp_port (default: localhost:19132)

Architecture

Minecraft Client → Cloudflare Tunnel → WebSocket Bridge → Local MC Server

• TCP Bridge: Handles Java Edition connections via persistent WebSocket
• UDP Bridge: Handles Bedrock Edition connections via WebSocket
• Cloudflared: Creates secure tunnels from Cloudflare edge to local bridges

Troubleshooting

"Cannot start TCP-WS-Bridge" or "Cannot start UDP-WS-Bridge"

Make sure the websockets package is installed:

pip install websockets

"Cannot reach MC" errors

Ensure your Minecraft server is running on the configured port before starting MineConnect.

Cloudflared not found

Install cloudflared and make sure it's in your PATH:

• Windows: Download from Cloudflare and add to PATH
• Linux: wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
• macOS: brew install cloudflared

Development

To modify the package:

1. Clone the repository
2. Install in editable mode: pip install -e server/
3. Make changes to files in server/mineconnect/
4. Changes take effect immediately

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Priyadarshan Mahankuda (httperry)

• Website: ideadev.me
• GitHub: @httperry

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Python and WebSockets
• Uses Cloudflare tunnels for secure connections
• Supports both Minecraft Java Edition and Bedrock Edition (via Geyser)

Support

For issues, questions, or contributions, please visit the GitHub repository.