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

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

Tunnel Backends

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

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

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