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