claude-remote-mcp

claude-remote-mcp

A Claude Code plugin that lets one running Claude Code session spawn and manage Claude Remote Control sessions on the same machine, then hand the URL/QR off to mobile or web so you can keep working from another device.

The plugin handles the things mobile and web cannot do locally:

• create folders or git worktrees, optionally git init a fresh repo
• spawn detached claude remote-control processes
• install plugins and MCP servers (the /plugin and /mcp slash commands are local-only and cannot run from claude.ai/code or mobile)
• list, stop, and merge-back lifecycle

Steering the spawned session itself — chat, approvals, transcript — stays in mobile / web. The plugin deliberately does not duplicate that.

See PRODUCT_BRIEF.md for product framing and architecture.md for technical details.

Requirements

• Claude Code >= 2.1.51 (Remote Control requirement). Check with claude --version.
• Node.js >= 20.
• Claude Code subscription (Pro or Max; Team and Enterprise need an admin to enable the Remote Control toggle).
• Outbound HTTPS to api.anthropic.com.
• API-key auth is not supported by Remote Control. The plugin's pre-flight check enforces this.

Install

The bundled dist/server.js is committed, so no npm install or build step is needed to consume the plugin.

Option A — Install via marketplace (recommended)

This repo doubles as a single-plugin marketplace (.claude-plugin/marketplace.json). In any Claude Code session:

/plugin marketplace add hieutrtr/claude-remote-mcp
/plugin install claude-remote-mcp@hieutrtr

Restart the session, or run /reload-plugins.

Verified end-to-end: marketplace add clones the GitHub repo, reads marketplace.json, registers a marketplace named hieutrtr. plugin install claude-remote-mcp@hieutrtr copies the plugin to ~/.claude/plugins/cache/hieutrtr/claude-remote-mcp/<version>/, records it in installed_plugins.json pinned to the published version field in plugin.json (and the git commit SHA as a fallback channel). Installed cache is ~1.3 MB, not 90 MB, because an .npmrc with omit=dev keeps the runtime build tools out of the user's cache.

Option B — Local dev / test (no install)

For a single session without persisting an install:

git clone https://github.com/hieutrtr/claude-remote-mcp.git
claude --plugin-dir /absolute/path/to/claude-remote-mcp

The --plugin-dir flag loads the plugin for that session only. If you also have it installed via marketplace, --plugin-dir takes precedence for that session.

claude plugin install does not accept a local path — it only resolves plugins from a configured marketplace (name@marketplace syntax). Use --plugin-dir for local-only testing.

Quickstart

After install, plugin slash commands are namespaced as /claude-remote-mcp:<name>:

> /claude-remote-mcp:spawn-remote ./migrations name=alembic

Absolute paths (e.g. /Users/you/myproject/demo) bypass project-dir resolution entirely for same-dir and session modes — they always land exactly where you specify. Use them when you want a guarantee.

Home-relative paths (e.g. ~/projects/demo or ~) are expanded to the current user's home directory before any resolution step, so they behave the same as absolute paths. (The shell doesn't expand ~ for arguments passed to MCP tools, so the plugin does it explicitly.)

Relative paths (e.g. ./demo) resolve against the orchestrator project directory, which the plugin determines through this chain (first match that does NOT point inside the plugin install cache wins):

1. CLAUDE_REMOTE_MCP_PROJECT_DIR — explicit user override.
2. CLAUDE_PROJECT_DIR — set by Claude Code for MCP server subprocesses.
3. MCP roots/list request, when the client advertises the roots capability.
4. $PWD — the shell launcher's working directory.
5. process.cwd() — last resort.

Any entry that resolves to a path inside ~/.claude/plugins/cache/... is rejected, not silently used — the only ways the plugin will ever mkdir into the plugin cache is if you pass an absolute path under it on purpose. If every strategy fails, spawn_remote_session returns INVALID_INPUT with a list of all attempted sources and the reason each was rejected, instead of silently creating files in the wrong place.

The spawn response includes project_dir_used and project_dir_source, and check_remote_ready exposes the same under orchestrator_project_dir, so misconfiguration is immediately visible.

If resolution fails on your machine, set the override before launching claude:

export CLAUDE_REMOTE_MCP_PROJECT_DIR="$PWD"
claude