mineconnect 1.1.0
Minecraft TCP/UDP to WebSocket bridge with Cloudflare tunnel support
Requires Python: >=3.8
Keywords: minecraft, tunnel, websocket, cloudflare, proxy, tcp, udp, bedrock, java-edition

# MineConnect

**Minecraft TCP/UDP to WebSocket bridge with Cloudflare tunnel support**

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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:
- **CLI Mode**: Interactive command-line interface
- **Daemon Mode**: Run in background
- **Python API**: Integrate into your code

## Installation

### From Source (Development)

```bash
cd c:\Projects\MineConnect\server
pip install -e .
```

### From PyPI (Future)

```bash
pip install mineconnect
```

## One-Time Setup

Before using MineConnect, run the tunnel setup (requires cloudflared installed):

```bash
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

```python
from mineconnect import mcs

# Use default ports (25565 for Java, 19132 for Bedrock)
session = mcs.config()
session.start()
```

### Custom Ports

```python
from mineconnect import mcs

# Custom Minecraft server ports
session = mcs.config(tcp_port=25566, udp_port=19133)
session.start()
```

### Single Tunnel Mode

```python
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

```python
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

### Interactive CLI

```bash
mineconnect-client
```

Interactive commands: `connect`, `disconnect`, `status`, `quit`

### Daemon Mode

```bash
# Connect both tunnels
mineconnect-client --both

# Connect Java only
mineconnect-client --java

# Custom domain
mineconnect-client --both --domain yourdomain.com
```

### Python API (Client)

```python
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](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:
```bash
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](https://ideadev.me)
- GitHub: [@httperry](https://github.com/httperry)

## License

This project is licensed under the MIT License - see the [LICENSE](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](https://github.com/httperry/MineConnect).