claude-mcp-tunnel

An MCP server that exposes your local dev servers to your phone through Claude Desktop.

Text Claude from your phone: "Start my project and give me a link" — get back a working URL.

Zero accounts. Zero config. Works with 25+ frameworks.

What Is This?

An MCP (Model Context Protocol) server that gives Claude Desktop the ability to:

1. Detect what framework your project uses (Next.js, Vite, FastAPI, etc.)
2. Start the dev server and install dependencies if needed
3. Tunnel it so your phone (or anyone) can reach it
4. Return the URL so you can open it immediately

It also ships as a standalone CLI (npx claude-mcp-tunnel) for use without Claude.

Quick Start — MCP Server (Claude Desktop)

Option A: Install via npm (easiest)

npm install -g claude-mcp-tunnel

Then add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "claude-mcp-tunnel": {
      "command": "claude-mcp-tunnel-server"
    }
  }
}

Option B: Clone from GitHub

git clone https://github.com/AustinRyan/claude-mcp-tunnel.git
cd claude-mcp-tunnel
npm install

Then add to your Claude Desktop config:

{
  "mcpServers": {
    "claude-mcp-tunnel": {
      "command": "node",
      "args": ["/absolute/path/to/claude-mcp-tunnel/mcp-server/index.js"]
    }
  }
}

Replace /absolute/path/to/claude-mcp-tunnel with where you cloned the repo.

Install cloudflared (required for public tunnels)

# macOS
brew install cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared

Restart Claude Desktop

Close and reopen Claude Desktop. The tools will appear automatically.

Use it

In Claude Desktop, say:

"Expose port 3000 and give me a URL"

or

"Start the project at /path/to/my-app and give me a link I can open on my phone"

MCP Tools

| Tool | Description | |------|-------------| | scan_ports | Scan common dev ports (3000, 5173, 8080, etc.) for running servers | | detect_project | Detect project framework from a directory | | expose_port | Expose a running port via tunnel, return a public URL | | start_and_expose | Full pipeline: detect framework, install deps, start server, tunnel, return URL | | start_full_stack | Start both backend + frontend for full-stack projects, expose frontend | | stop_tunnels | Kill all active tunnels and servers | | get_status | Show all active tunnels, ports, and URLs |

Example: Full-Stack Project

For a project with a FastAPI backend and Vite frontend:

"Start the full stack project at /path/to/my-app — the frontend is in the frontend/ directory, the backend runs with uvicorn backend.app:app --reload --port 8000"

Claude calls start_full_stack → starts backend on 8000 → starts frontend on 5173 → tunnels the frontend → returns the URL.

Use with Claude Dispatch

Text from your phone via Dispatch:

"Start my project and give me a link I can open on my phone"

The flow:

Phone → Dispatch → Cowork (your Mac) → MCP tool → URL back to phone

Claude calls start_and_expose, gets the tunnel URL, and texts it back to you.

Standalone CLI (No Claude Required)

Works as a regular CLI tool for anyone:

# Use directly (no install needed)
npx claude-mcp-tunnel

# Or install globally
npm install -g claude-mcp-tunnel

CLI Commands

# Auto-detect running server and expose it
claude-mcp-tunnel

# Expose a specific port
claude-mcp-tunnel 3000

# Detect project, install deps, start server, expose — all in one
claude-mcp-tunnel start

# Scan what's running on common dev ports
claude-mcp-tunnel scan

# Get your local IP
claude-mcp-tunnel ip

CLI Flags

| Flag | Short | Description | |------|-------|-------------| | --port <n> | -p | Specify port | | --dir <path> | -d | Project directory | | --local | -l | Local network only (same WiFi) | | --bore | -b | Force bore tunnel | | --ssh | -s | Force localhost.run tunnel | | --start | | Start server if not running | | --quiet | -q | Minimal output | | --version | -v | Show version | | --help | -h | Show help |

Tunnel Backends

Auto-selects the best available backend. No accounts required for any of them.

| Backend | Speed | Install Required | Access | |---------|-------|------------------|--------| | Cloudflare Tunnel | Fast | brew install cloudflared | Public HTTPS (anywhere) | | bore | Fast | brew install bore-cli | Public (anywhere) | | localtunnel | Good | None (pure Node.js) | Public (anywhere) | | localhost.run | Good | None (uses SSH) | Public (anywhere) | | Local IP | Instant | None | Same WiFi only |

Fallback order: Cloudflare → bore → localtunnel → localhost.run → local IP.

Cloudflare Tunnel is recommended — it produces HTTPS URLs on a trusted domain (trycloudflare.com) that ISPs and security software won't block.

Supported Frameworks (25+)

Node.js: Next.js, Vite, Create React App, Angular, Vue CLI, SvelteKit, Gatsby, Remix, Nuxt, Astro, Express, Fastify, NestJS, Storybook, Docusaurus, Eleventy

Python: FastAPI, Flask, Django, Streamlit

Other: Rust (Cargo), Go, Ruby on Rails, Laravel (PHP), Hugo, Jekyll, Static HTML

Automatically detects the framework, determines the correct start command, and handles package manager differences (npm, yarn, pnpm, bun).

How It Works

Your Phone                    Your Computer
    │                              │
    │  "start my project"          │
    │  (via Dispatch/Claude)       │
    │─────────────────────────────>│
    │                              │  MCP server:
    │                              │  1. Detects framework (Vite)
    │                              │  2. Installs deps (npm install)
    │                              │  3. Starts server (npm run dev)
    │                              │  4. Creates Cloudflare tunnel
    │                              │
    │  https://xyz.trycloudflare.com
    │<─────────────────────────────│
    │                              │
    │  Open URL on phone           │
    │  App loads through tunnel    │
    │                              │

Programmatic API

const tunnel = require("claude-mcp-tunnel");

// Scan for running servers
const services = await tunnel.scanPorts();

// Detect project type
const project = tunnel.detectProject("/path/to/project");

// Start a server
const server = await tunnel.startServer({ dir: "/path/to/project" });

// Create a tunnel
const result = await tunnel.autoExpose(3000);
console.log(result.url); // https://abc123.lhr.life

// Cleanup
tunnel.killAllTunnels();
tunnel.killAllServers();

Troubleshooting

| Problem | Solution | |---------|----------| | Tools don't appear in Claude Desktop | Restart Claude Desktop. If using npm, verify claude-mcp-tunnel-server is in your PATH (which claude-mcp-tunnel-server). | | "Cannot find module" errors | Run npm install -g claude-mcp-tunnel to reinstall, or npm install if using the cloned repo. | | Tunnel URL blocked by ISP | Install cloudflared (brew install cloudflared). Cloudflare Tunnel uses trycloudflare.com which ISPs trust. | | Vite "host not allowed" error | Add server: { allowedHosts: true } to your vite.config.js. | | Tunnel fails, only local IP works | Install cloudflared. Without it, falls back to bore → localtunnel → SSH → local IP. | | Server starts but wrong port | Check your project's config (e.g. vite.config.js) for hardcoded ports. Pass the correct port via frontend_port. | | MCP server crashes silently | Check Claude Desktop's MCP logs. Server logs go to stderr. |

Project Structure

claude-mcp-tunnel/
├── mcp-server/
│   └── index.js          # MCP server (7 tools, stdio transport)
├── src/
│   ├── index.js           # Public API exports
│   ├── config.js           # Framework definitions (25+)
│   ├── scanner.js          # Port scanning & service detection
│   ├── detector.js         # Project framework detection
│   ├── starter.js          # Dev server startup & deps
│   ├── tunnel.js           # Tunnel manager (bore/SSH/local)
│   └── display.js          # Terminal formatting & QR codes
├── bin/
│   └── devgate.js          # CLI entry point
├── skills/                 # Claude Code plugin skills
└── package.json

License

MIT