Shiro Remote MCP

Connect Claude Code to your browser-based Shiro instance via WebRTC

What is this?

Shiro Remote lets you control a Shiro browser instance directly from Claude Code running on your computer. No servers needed — it uses WebRTC for a direct peer-to-peer connection.

Quick Start

1 Install — Run this once to add Shiro to Claude Code:

npx shiro-mcp --install

Then restart Claude Code.

2 Connect — In Shiro, run remote start to get a connection code, then tell Claude:

"Connect to Shiro with code fluffy-cloud-shimutako"

Done! Claude can now execute commands, read/write files, and run JavaScript in your browser.

Available Tools

All tools are namespaced under shiro: in Claude Code.

connect

Connect to a Shiro instance using a connection code from remote start

reconnect

Reconnect after browser page reload (uses saved code, browser must run remote start again)

disconnect

Disconnect and clear the saved connection code

status

Check connection status: connected, code, status

exec

Execute shell commands — 220+ commands including hc, serve, image, npm, node

read

Read a file from /home/user (persistent) or /tmp

write

Write a file to the virtual filesystem

list

List directory contents

eval

Execute JavaScript in browser (use JSON.stringify for objects)

Connection Codes

Connection codes like fluffy-cloud-shimutako provide ~46 bits of entropy, making them virtually impossible to guess. They expire after 5 minutes.

The code has three parts:

Adjective (200 options) — fluffy, cosmic, brave...
Noun (200 options) — cloud, fox, crystal...
Syllables (64⁴ options) — shimutako, karinobe...

Only the first two parts are shown in the Shiro banner for privacy — someone watching your screen can't hijack your session.

Manual Configuration

If npx shiro-mcp --install doesn't work, add this to your Claude config manually:

// ~/.claude.json (Claude Code CLI)
// or ~/Library/Application Support/Claude/claude_desktop_config.json (Desktop)
{
  "mcpServers": {
    "shiro": {
      "command": "npx",
      "args": ["-y", "shiro-mcp"]
    }
  }
}

Requirements

Node.js 18+ required. The node-datachannel package provides WebRTC support.

Shiro Commands

Commands available in the Shiro terminal:

remote start    # Start a remote session, get connection code
remote stop     # Stop the current remote session
remote status   # Check connection status
clear           # Refresh the banner to show/hide connection code

For AI Assistants

This section helps AI assistants (Claude, etc.) use Shiro MCP effectively.

Shell Commands (exec)

Shiro provides 220+ commands. Run help for full list. Key Shiro-specific commands:

hc              # Hypercompact DOM navigation (see below)
serve <dir>     # Start virtual HTTP server
servers         # List active servers
serve stop <p>  # Stop server on port
image save/load # Filesystem snapshots
npm install     # Install npm packages
node file.js    # Run JavaScript files

Hypercompact (hc) — Token-Efficient DOM Navigation

hc live           # Attach to live page DOM
hc look           # List interactive elements (@0, @1, ...)
hc @N             # Click element N
hc q <selector>   # Query elements (CSS selector)
hc t100           # Get text content (100 char limit)
hc h50            # Get HTML (50 char limit)
hc a              # Show attributes
hc close          # Detach from DOM

eval Tool — Important

Objects return "[object Object]". Always wrap in JSON.stringify():

// Wrong - returns "[object Object]"
{ width: innerWidth }

// Correct - returns actual values
JSON.stringify({ width: innerWidth })

Filesystem Layout

/home/user    # User files (persistent, IndexedDB)
/tmp          # Temporary files

Troubleshooting

Connection fails immediately

Make sure the code hasn't expired (5 minute timeout). Run remote start again in Shiro to get a fresh code.

WebRTC connection times out

Some corporate networks block WebRTC. Try from a different network or use a VPN.

Connection lost after browser reload

When the Shiro browser page reloads, run remote start in Shiro again, then use the reconnect tool (it remembers the last code).

node-datachannel build errors

The package requires Node.js 18+ and a C++ compiler. On most systems it installs pre-built binaries. If compilation is needed:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential cmake