npm package: @mcp-use/tunnel
Description: Simple bore tunnel client - one command to get a public URL
Latest version: 0.1.4

# Bore with Subdomain Routing

A complete solution for running [bore](https://github.com/ekzhang/bore) with **ngrok/localtunnel-style subdomain routing** and **automatic HTTPS via Cloudflare**.

```
┌──────────────────────────────────────────────────────────────┐
│  User types: https://happy-cat.local.mcp-use.run            │
└─────────────────────────┬────────────────────────────────────┘
                          │ HTTPS (Cloudflare handles SSL)
                          │
┌─────────────────────────▼────────────────────────────────────┐
│              Cloudflare (Free SSL + DDoS)                    │
└─────────────────────────┬────────────────────────────────────┘
                          │ HTTP
                          │
┌─────────────────────────▼────────────────────────────────────┐
│         HTTP Proxy (subdomain routing)                       │
│         happy-cat → localhost:8123                           │
└─────────────────────────┬────────────────────────────────────┘
                          │
┌─────────────────────────▼────────────────────────────────────┐
│              Bore Server (TCP tunnels)                       │
└─────────────────────────┬────────────────────────────────────┘
                          │ Tunnel
                          │
┌─────────────────────────▼────────────────────────────────────┐
│        Bore Client (user's local machine)                    │
│        bore local 3000 --to server.com                       │
└─────────────────────────┬────────────────────────────────────┘
                          │
┌─────────────────────────▼────────────────────────────────────┐
│            Local Web Server (port 3000)                      │
└──────────────────────────────────────────────────────────────┘
```

## 🌟 Features

- ✨ **Subdomain routing** - `happy-blue-cat.local.mcp-use.run` style URLs
- 🔒 **Automatic HTTPS** - Free SSL via Cloudflare
- 🔐 **Token-based authentication** - Prevents port scanning and tunnel hijacking
- 🛡️ **Path restrictions** - Configurable path restrictions (default: `/mcp**` and `/mcp-use**`, or allow all paths with `/`)
- 🌐 **WebSocket support** - Full bidirectional communication
- 🎯 **REST API** - Simple tunnel management
- 📦 **NPX client** - No installation needed for clients
- 🐳 **Docker ready** - Easy deployment
- 🚀 **Railway/Render compatible** - Deploy in minutes

## 📦 What's Included

This repository contains:

1. **`@mcp-use/tunnel`** - NPX client for bore tunnels (no Rust needed!)
2. **`proxy-server`** - HTTP proxy with subdomain routing
3. **Cloudflare integration** - HTTPS without managing certificates
4. **Complete deployment guides** - Railway, Docker, VPS, etc.

## 🚀 Quick Start

### Server Setup (5 minutes)

**Option 1: Railway (Easiest)**

1. Fork this repo
2. Deploy to [Railway](https://railway.app)
3. Set environment variable: `BASE_DOMAIN=your-domain.com`
4. Follow [CLOUDFLARE-SETUP.md](./CLOUDFLARE-SETUP.md)

**Option 2: Docker**

```bash
cd proxy-server
docker-compose up -d
```

See [DEPLOYMENT.md](./DEPLOYMENT.md) for more options.

### Client Usage

```bash
# 1. Start your local service
python -m http.server 3000

# 2. Create tunnel - that's it!
npx @mcp-use/tunnel 3000

# Output:
# ╭─────────────────────────────────────────────╮
# │  🎉 Tunnel Created Successfully!           │
# ╰─────────────────────────────────────────────╯
#
#   🌐 Public URL:
#      https://happy-blue-cat.local.mcp-use.run
#
#   📍 Subdomain: happy-blue-cat
#   🔌 Local Port: 3000
#   🚪 Remote Port: 8456
#
# ╭─────────────────────────────────────────────╮
# │  Press Ctrl+C to close the tunnel          │
# ╰─────────────────────────────────────────────╯

# 3. Access your service!
curl https://happy-blue-cat.local.mcp-use.run
```

### Railway Deployments (Custom Control Port)

Railway exposes TCP ports with random external ports (e.g., `caboose.proxy.rlwy.net:23894 → :7835`). The server includes a **custom bore build** with `--control-port` support.

**⚠️ Important:** The tunnel ports (8000-9000) that bore assigns are **NOT externally accessible** - they're only used internally by the HTTP proxy on Railway. Users access tunnels via **subdomain URLs** (e.g., `https://happy-cat.local.mcp-use.run`), not direct port access.

The API response includes the correct connection command:

```bash
# Get connection info from API
curl https://your-domain.com/api/tunnels

# Response includes:
# "bore_command": "bore local <PORT> --to caboose.proxy.rlwy.net --control-port 23894"
```

**Usage with Railway:**

The `mcp-tunnel` command automatically uses the correct server configuration:

```bash
# Set environment variables once
export BORE_SERVER=caboose.proxy.rlwy.net
export BORE_CONTROL_PORT=23894

# Then just use the simple command
npx @mcp-use/tunnel 3000
# Automatically connects to Railway and shows your URL!
```

**Note:** The package includes custom bore binaries with `--control-port` support built-in.

## 📚 Documentation

- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - How everything works together (READ THIS FIRST!)
- **[SECURITY.md](./SECURITY.md)** - Security guide & best practices
- **[ADMIN-CLI.md](./ADMIN-CLI.md)** - Admin CLI for tunnel management
- **[PATH-RESTRICTIONS.md](./PATH-RESTRICTIONS.md)** - Path restrictions security feature
- **[CLOUDFLARE-SETUP.md](./CLOUDFLARE-SETUP.md)** - Complete Cloudflare configuration guide
- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - Deploy to Railway, Docker, VPS, etc.
- **[RAILWAY-TCP-BRANDING.md](./RAILWAY-TCP-BRANDING.md)** - Brand Railway TCP proxy domain
- **[CUSTOM-BORE-SETUP.md](./CUSTOM-YOUR-BORE-SETUP.md)** - Build & distribute custom bore binaries
- **[proxy-server/README.md](./proxy-server/README.md)** - HTTP proxy documentation

## ❓ FAQ

### Do I need to handle HTTPS in my app?

**No!** If you use Cloudflare (recommended), it handles SSL termination. Your app only needs HTTP (port 80).

See: [CLOUDFLARE-SETUP.md](./CLOUDFLARE-SETUP.md)

### How is this different from ngrok?

| Feature           | ngrok      | localtunnel | This Project        |
| ----------------- | ---------- | ----------- | ------------------- |
| Subdomain routing | ✅         | ✅          | ✅                  |
| Custom domains    | ✅ (paid)  | ✅          | ✅ (free)           |
| Self-hostable     | ❌         | ✅          | ✅                  |
| HTTPS             | ✅         | ✅          | ✅ (via Cloudflare) |
| Free tier limits  | 40 req/min | None        | None (self-hosted)  |
| Written in        | Go         | Node.js     | Rust + Node.js      |

### How much does it cost?

- **Cloudflare:** FREE ✅
- **Domain:** ~$10/year
- **Railway:** ~$5/month (500 hours free tier)
- **Total:** ~$10/year + optional $5/month

Or self-host on a $4-6/month VPS!

### Can I use my own domain?

Yes! Any domain works. Just configure DNS and Cloudflare:

1. Point `*.local.your-domain.com` to your server
2. Set `BASE_DOMAIN=local.your-domain.com`
3. Configure Cloudflare for free HTTPS

See: [CLOUDFLARE-SETUP.md](./CLOUDFLARE-SETUP.md)

## 🏗️ Architecture

### Components

1. **Bore Server** (Rust)

   - TCP tunnel server
   - Listens on port 7835 (control) + 8000-9000 (tunnels)
   - From [github.com/ekzhang/bore](https://github.com/ekzhang/bore)

2. **HTTP Proxy** (Node.js)

   - Routes HTTP traffic based on subdomain
   - Manages subdomain → port mappings
   - REST API for tunnel management

3. **Cloudflare** (External)

   - SSL/TLS termination
   - DDoS protection
   - Global CDN
   - **FREE!**

4. **NPX Client Wrapper** (Node.js)
   - Downloads bore binary automatically
   - No Rust installation needed
   - Works with `npx` directly

### Data Flow

```
User Request (HTTPS)
    → Cloudflare (SSL termination)
    → HTTP Proxy (subdomain routing)
    → Bore Tunnel (TCP proxy)
    → Bore Client (user's machine)
    → Local Service
```

## 🛠️ Development

### Prerequisites

- Node.js 18+
- Rust (for building bore)
- Docker (optional)

### Local Development

```bash
# Install dependencies
cd proxy-server
yarn install

# Start proxy server (requires bore binary)
yarn start

# Or use Docker
docker-compose up
```

### Project Structure

```
mcp-use-tunnel/
├── bore/                    # Bore source code (Git submodule)
├── proxy-server/            # HTTP proxy with subdomain routing
│   ├── index.js            # Main proxy server
│   ├── package.json
│   ├── Dockerfile
│   └── docker-compose.yml
├── cli.js                  # NPX bore wrapper
├── package.json            # bore-npx package
├── CLOUDFLARE-SETUP.md     # Cloudflare guide
├── DEPLOYMENT.md           # Deployment guide
└── README.md               # This file
```

## 🔒 Security Features

- ✅ **Token-based authentication** - Prevents port scanning attacks
- ✅ **IP-based validation** - Prevents token theft
- ✅ **Path restrictions** - Only `/mcp**` and `/mcp-use**` paths allowed
- ✅ **Rate limiting** - Prevents API abuse
- ✅ **Connection limits** - Prevents resource exhaustion
- ✅ **Automatic cleanup** - Expired tunnels removed automatically
- ✅ **Pre-assigned ports** - No random port scanning possible

See [SECURITY.md](./SECURITY.md) for details.

## 🤝 Contributing

Contributions welcome! Some ideas:

- [ ] Web dashboard for tunnel management
- [ ] Metrics and monitoring
- [ ] Data transfer limits
- [ ] More client wrappers (Python, Go, etc.)

## 📝 License

MIT

## 🙏 Credits

- [bore](https://github.com/ekzhang/bore) by [@ekzhang](https://github.com/ekzhang) - The amazing TCP tunnel
- [Cloudflare](https://cloudflare.com) - Free SSL and DDoS protection
- Inspired by [ngrok](https://ngrok.com) and [localtunnel](https://github.com/localtunnel/localtunnel)

## 🔗 Links

- [Bore GitHub](https://github.com/ekzhang/bore)
- [Railway](https://railway.app)
- [Cloudflare](https://cloudflare.com)
- [Deploy to Railway Button](https://railway.app/new/template?template=...)

## 📧 Support

- Open an issue on GitHub
- Check [CLOUDFLARE-SETUP.md](./CLOUDFLARE-SETUP.md) for common issues
- Read [DEPLOYMENT.md](./DEPLOYMENT.md) for platform-specific help

---

Made with ❤️ for the developer community