Claude Code Bridge

Lets a Claude conversation send tasks to a local Claude Code CLI instance and get the results back, so you can talk to Claude and have it relay build instructions to Claude Code running on your laptop.

Requirements

• Node.js 18+ installed on the laptop

• Claude Code CLI installed and working (claude command available in a terminal)

• The project folder you want Claude Code to build in

Related MCP server: MCP-Claude Code Bridge

Setup

1. Copy this whole claude-code-bridge folder onto your laptop.

2. Open a terminal in that folder and install dependencies:

   npm install

3. Set the default project directory Claude Code should work in (the folder for your video app project), either by:

   • editing DEFAULT_PROJECT_DIR at the top of server.js, or

   • setting an environment variable before starting it:

     set CLAUDE_PROJECT_DIR=C:\path\to\your\project

     (use export instead of set on Mac/Linux)

4. Test it runs standalone:

   npm start

   It should sit there waiting silently (it talks over stdio, not the terminal) — that's normal. Ctrl+C to stop.

5. Register it as a connector in your Claude account settings as a custom/local MCP server, pointing at:

   node C:\path\to\claude-code-bridge\server.js

   (Exact registration steps depend on the current Claude settings UI — look for "Add custom connector" / "Local MCP server" under Settings.)

Once connected, ask Claude (in chat) to use the run_claude_code_task tool with an instruction, e.g. "build a Swift project that..." — it will relay that to Claude Code on your laptop and read back what happened.

Using it from the Claude iPhone/mobile app

The stdio setup above only works for MCP clients running on the same machine (Claude Code CLI, Claude Desktop). The Claude mobile app can't spawn a local process — it needs a server reachable over HTTPS. This repo supports that as a second mode:

1. Pick a long random token (this guards the endpoint — anyone with it can run tasks on your laptop). Generate one, e.g.:

   node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"

2. Start the server in HTTP mode with that token (PowerShell):

   $env:BRIDGE_TOKEN = "paste-your-token-here"
   npm run start:http

   It listens on https://localhost:8787/mcp/<your-token> (change the port with $env:PORT). GET /health returns ok with no auth required, for quick sanity checks. TLS uses the cert/key at certs/fullchain.pem / certs/privkey.pem by default (override with $env:TLS_CERT_PATH / $env:TLS_KEY_PATH).

   The token is part of the URL path, not a header — the Claude mobile app's custom-connector form has no field for custom headers, and treats any 401 as "this server needs OAuth," which this server doesn't implement. Putting the token in the path means the very first request already carries it and nothing ever 401s.

3. Expose that port to the internet with a tunnel, e.g. Cloudflare Tunnel:

   cloudflared tunnel --url http://localhost:8787

   or ngrok http 8787. Either prints a public https://... URL that forwards to your laptop. Keep the tunnel and the server running the whole time you want mobile access to work.

4. In the Claude app, go to Settings → Connectors → Add custom connector, and enter:

   • URL: https://<your-tunnel-domain>/mcp/<your-token>

   That's it — just the one URL field. Don't put anything after /mcp/ except the raw token, and don't rely on the "Connect" button doing an OAuth handshake; this server has none, so the first request through that URL is what authenticates you.

   Once added, ask Claude on your phone to use the run_claude_code_task tool the same way you would from a desktop session.

5. When you're done, stop the tunnel and the server (Ctrl+C both) — don't leave the tunnel running unattended, since the token is the only thing standing between the internet and claude -p running on your machine.

Async task queue (HTTP mode)

The MCP tool call above blocks the whole request until Claude Code finishes, which can be minutes — long enough for a tunnel or client timeout to drop the connection. In HTTP mode, two plain REST endpoints let you fire a task and poll for it instead, backed by the same persistent Claude Code session and its one-at-a-time queue:

• POST /task with a JSON body { "prompt": "...", "project_dir": "..." (optional) } and header Authorization: Bearer <your-token> — returns immediately with { "job_id": "...", "status": "pending" }.

• GET /status/<job_id> (same auth header) — returns { "job_id": "...", "status": "pending" | "done", "result": "..." }. result is null until the job finishes.

Job state lives in memory only, so it's lost if the server restarts.

Notes / limitations

• One task runs at a time; a second call while one is running will queue behind it (this simple version doesn't parallelize).

• Long tasks (over ~10 minutes) will time out — adjust TASK_TIMEOUT_MS in server.js if your builds take longer.

• The bridge only relays text output. It cannot show you the video files Claude Code produces — you'll still open those directly on your laptop.