Shellby MCP server

[!CAUTION] Shellby MCP runs with the full permissions of your local macOS user. An authorized ChatGPT caller can run commands, edit files, fetch webpages, and control supported applications.

Capabilities

Capability	Description
Persistent shells	Named login shells retain cwd, environment, processes, and command history across MCP calls.
Native apply_patch	Native ChatGPT apply_patch binary used to edit files independently of shell state.
Computer Use	Focused macOS observation and interaction backed by Peekaboo.
Browser subagents	Detached ChatGPT Web conversations with follow-up context and concurrent result retrieval.
Web and images	Rendered webpage extraction, bounded document pagination, and native image transport.
Dynamic skills	Reusable workflows loaded from <workspace>/skills/*/SKILL.md.

Requirements

• macOS on Apple Silicon or Intel
• Node.js 22.18.0 or newer
• npm
• An ngrok account and CLI
• A ChatGPT Plus or Higher account with Developer Mode turned on

Google Chrome is optional and is used for browser-backed subagents. Computer Use is optional and uses the Peekaboo package installed with this repository.

Quick start

Install with your coding agent

skills/install-shellby-mcp/SKILL.md

Manual install

[!TIP] The manual install process should be ran from Terminal.app for the best macOS permission context.

1. Install ngrok, clone the repository, and install dependencies:

   brew install --cask ngrok
   git clone https://github.com/Serbyte-Development/shellby-mcp.git
   cd shellby-mcp
   npm ci
   

2. Authenticate ngrok:

   ngrok config add-authtoken <your-token>
   

   Get an authtoken from the ngrok dashboard if needed.

3. Create the active Shellby config:

   npm run setup -- --config-only
   

   Review .shellby/config.toml and edit any values you want to customize. The generated file shows every supported setting: defaults are active, and settings without defaults are commented examples.

4. Run guided setup:

   npm run setup
   

   Setup checks the machine, prepares the workspace, and builds Shellby MCP. It also checks Computer Use and prepares the dedicated ChatGPT Chrome profile when those tool groups are enabled.

5. Run the first managed start from Terminal.app:

   npm start
   

   This creates or reuses the repository-local PM2 runtime, starts Shellby MCP and ngrok, launches the configured ChatGPT browser when agent tools are enabled, waits for local health, and prints the public /mcp URL. Starting from Terminal.app gives the managed process tree the intended macOS permission context for Computer Use.

6. In ChatGPT Developer Mode, create a custom MCP app with the printed https://.../mcp URL and select No Auth.

[!IMPORTANT] The first trusted remote tool call binds the installation to that ChatGPT subject. Use npm run auth:reset only when you intend to clear that binding.

Verify the installation

npm run status
curl -fsS http://127.0.0.1:3333/healthz
npm run print-url

The default local MCP endpoint is http://127.0.0.1:3333/mcp; root port in .shellby/config.toml changes the listener and health-check port.

Optional capabilities

Shellby ships a package-local Peekaboo CLI build that matches its Computer Use adapter. Check or grant permissions with:

npm run setup:computer

Screen Recording enables observation. Accessibility and Event Synthesizing enable actions. Shellby always uses its bundled Peekaboo executable so the adapter and CLI stay on the tested version together.

See Computer Use for runtime details.

[!WARNING] Browser-backed ChatGPT subagents automate ChatGPT Web and may conflict with OpenAI's Terms of Use. Disable them with tools.subagents = false in .shellby/config.toml. Use these features at your own risk.

Run the dedicated browser setup when Chrome was unavailable during initial setup or when you want to configure it later:

npm run setup:chatgpt

This creates a dedicated Chrome profile under <state_dir>/chatgpt-chrome and attaches over CDP at 127.0.0.1:9222. state_dir defaults to ~/.shellby. Sign into ChatGPT once in that profile. Future npm start runs launch it automatically while subagent tools are enabled.

Conversation URL and turn count are persisted for reused agent_id values. Use npm run reset-agents to forget those local mappings.

See Browser ChatGPT Subagents for lifecycle details.

Operations

Command	Purpose
npm start	Build and start or reload Shellby MCP, ngrok, and enabled supporting services.
npm run restart	Rebuild, clear the audit log, and reload services using the existing PM2 daemon.
npm run restart -- --hard	Rebuild and recreate Shellby's PM2 daemon from a healthy Terminal.app session.
npm run status	Show PM2 process state.
npm run logs	Follow PM2 logs.
npm run pm2 -- <args>	Run a PM2 command against Shellby's dedicated daemon.
npm run print-url	Print the active public /mcp URL.
npm run stop	Stop the managed Shellby MCP and ngrok processes.
npm run auth:reset	Clear the bound remote ChatGPT subject after confirmation.
npm run reset-agents	Forget persisted subagent conversation mappings.
npm run ui:phone	Expose only the built dashboard UI/API on LAN port 6001; /mcp stays local.

PM2 is installed as a repository dependency. All Shellby PM2 commands use <state_dir>/pm2 for their daemon, sockets, logs, and process state. state_dir defaults to ~/.shellby. This is separate from the default ~/.pm2 daemon used by other projects; use npm run pm2 -- <args> for direct access to Shellby's daemon.

Use npm run restart for routine code or config changes, including from shell_run. It keeps the PM2 daemon, reloads ngrok, then reloads MCP. The initiating shell and MCP connection may close; after services return, make a fresh tool call. Build failures leave running services and the audit log intact. The authenticated ChatGPT Chrome profile is reused.

For macOS permission or service-context problems, run npm run restart -- --hard from a healthy Terminal.app session. This also recreates Shellby's dedicated PM2 daemon. Hard restart refuses to run inside Shellby because stopping that daemon would kill the command responsible for starting its replacement.

If Shellby was previously running under the default shared daemon, move it once from Terminal.app before using the new commands:

PM2_HOME="$HOME/.pm2" ./node_modules/.bin/pm2 delete shellby-mcp shellby-ngrok
npm run restart

The first command removes only Shellby's old app entries, leaving the shared daemon and other projects running. If an older installation still has a shellby-cursor-host entry in that daemon, delete that entry there too. The migration briefly interrupts Shellby; it does not erase authentication or browser profiles. Future restarts need only npm run restart.

Update an existing installation

git pull
npm ci
npm run setup -- --config-only
npm start

Configuration

Shellby's public configuration is the gitignored .shellby/config.toml. npm run setup creates a config showing every supported setting for new installations, with defaults active and the optional ngrok.url shown as a commented example. Uncomment and customize that URL to use a reserved ngrok endpoint; leaving it commented lets ngrok assign the public URL. Existing files are left untouched, preserving their values, comments, and formatting. Missing settings use defaults automatically. Invalid values produce a warning and fall back individually; unknown keys warn and are ignored. Valid TOML formatting—including reordered sections, dotted keys, and inline tables—is accepted. Malformed TOML syntax still needs correction; errors show the location and never rewrite your file.

The TOML surface currently owns the runtime state directory, workspace, shell path, ChatGPT CDP/project routing, MCP tool-output format, and startup-static tool groups. state_dir controls machine-local Shellby state such as authentication, subagent persistence, the dedicated Chrome profile, and the PM2 daemon; it defaults to ~/.shellby. The generated config enables every tool group and defaults tool output to compact. Setting a group to false removes those tools from tools/list after Shellby restarts and skips its supporting runtime service where one exists. start_here is always published. For example, this customization disables browser-backed agents and Computer Use:

state_dir = "~/.shellby"
workspace = "~/Desktop/agent-workspace"

[shell]
path = "/bin/zsh"
rtk = false

[chatgpt]
cdp_endpoint = "http://127.0.0.1:9222"
project_url = "https://chatgpt.com/"
max_delegated_agents = 3

[mcp]
tool_output = "compact"

[tools]
review = true
shell = true
apply_patch = true
subagents = false
web = true
skills = true
image = true
computer = false

chatgpt.max_delegated_agents sets the maximum number of subagent IDs per main-agent session. It defaults to 3; invalid values warn and fall back to 3. Set a positive integer to override it. Saved agents and in-flight creations count toward the limit; existing IDs remain reusable even if the limit is lowered. The per-call batch limit remains three. Older configs can omit this field. To override it, add it under [chatgpt], then restart Shellby after changing its value.

mcp.tool_output controls the representation used for ordinary tool results. compact is optimized for model context and omits public output schemas; structured preserves each tool's structured result and output schema for MCP clients that use them. Computer Use and image_view keep their native MCP content in either mode. Changing this setting requires a Shellby restart.

agent-commands.yaml records tool usage. Failed entries include a bounded error: line with the original cause's code and message, returned failure details, or captured shell failure output. npm run logs follows the existing PM2 process logs.

shell.rtk defaults to false, so RTK is not required to install or run Shellby. To enable transparent RTK command rewriting, install RTK Token Killer with brew install rtk, set shell.rtk = true, and restart Shellby. Shellby resolves that executable from startup PATH, then uses the resolved absolute path for supported rewrites regardless of the shell command's cwd. Unsupported rewrites and RTK failures fall back to the original command. Shellby keeps the caller's original command for request identity, auditing, and command previews, and disables RTK's separate failure tee, telemetry, and persistent history for Shellby-launched commands while still loading normal RTK filtering/exclusion configuration.

Shellby does not use a repository .env file. User-configurable Shellby settings come only from .shellby/config.toml; external tools use their normal machine-level configuration. In particular, ngrok is resolved from PATH and authentication is configured with ngrok config add-authtoken. Chrome is discovered in the normal macOS application locations, and Shellby uses its bundled Peekaboo build. The loopback host and internal runtime limits remain code-owned in src/config.ts.

Running two copies

Give each repository copy its own state directory, MCP port, and ChatGPT CDP port when agent tools are enabled. Copies using ngrok also need separate ngrok API ports and public URLs. Changing only state_dir separates saved state and PM2, but does not prevent port collisions. In the second copy's .shellby/config.toml, merge these values into the existing root and sections:

state_dir = "~/.shellby-second"
port = 3334

[ngrok]
api_port = 4041
url = "https://your-second-reserved-domain.ngrok.app"
pooling_enabled = false

[chatgpt]
cdp_endpoint = "http://127.0.0.1:9223"

Use a real, distinct ngrok URL available to your account. Keep pooling disabled for independent copies. If your config is missing, run npm run setup -- --config-only first, then edit it before full setup or startup. Run npm run setup in the new copy, sign into its dedicated Chrome profile if agent tools are enabled, then run npm start from Terminal.app. Run npm run print-url in each repository to get that copy's connector URL.

Each copy's PM2 commands, including hard restart, target its configured state directory. Authentication, subagent mappings, and Chrome profiles stay separate. ngrok credentials remain in its native user config; Shellby writes only an API-address overlay at <state_dir>/ngrok-agent.json. The dashboard uses the copy's MCP port (http://127.0.0.1:3334/ui/ for this example); the Vite development proxy also reads that port. Workspace files and the macOS desktop are still shared unless you select a separate workspace; Computer Use still controls the same desktop.

Local-only MCP

To run without ngrok, add or update this setting in .shellby/config.toml:

[ngrok]
enabled = false

Then use the usual npm start or npm run restart. PM2, enabled tool services, Chrome startup, and the optional dashboard still work. Setup and preflight skip ngrok installation/authentication checks. Startup removes any existing shellby-ngrok process from this instance's PM2 daemon before reloading MCP; a cleanup failure stops startup. Separately managed tunnels are outside this setting's scope.

npm run print-url prints http://127.0.0.1:<port>/mcp for your local MCP client. A new installation can run npm run setup -- --config-only, set ngrok.enabled = false, then run full setup without installing ngrok. The setting defaults to true, so existing configurations retain their behavior. Reserved URL and pooling values remain saved for later re-enabling. Local-only copies do not need a separate ngrok API port or public URL.

Troubleshooting

If the endpoint stays offline after restarting, check npm run status and npm run logs from Terminal.app. Run npm start if services are stopped. npm run print-url reports the active ngrok endpoint; an offline reserved URL does not by itself mean your config changed. Routine restart through shell_run may disconnect its own call while PM2 brings MCP back.

Run:

npm run preflight
npm run status
npm run logs

preflight checks the supported macOS/Node environment, local dependencies, ngrok installation, and ngrok authentication. If /healthz does not become available after startup, inspect PM2 status and logs first.

Run npm run setup:computer from Terminal.app and follow Peekaboo's permission guidance. Keep the managed Shellby process associated with the same intended Terminal permission context.

Run npm run restart -- --hard from a newly opened Terminal.app session. This recreates Shellby's dedicated PM2 daemon as well as Shellby MCP and ngrok. A stale macOS session inherited by PM2 can cause Chromium to abort before navigation and DNS lookups to fail even while MCP remains reachable. Ordinary restart retains the daemon's session and cannot repair that context. Daemon isolation does not make PM2 independent of Terminal's macOS session; keep Terminal.app running until PM2 is managed through a macOS LaunchAgent.

More startup and recovery details are in Configuration and Startup.

Security

• The checked-in ngrok traffic policy exposes the local MCP endpoint to ChatGPT.
• Direct localhost MCP access is unauthenticated. Do not expose the local endpoint through another untrusted proxy.
• Trusted remote tool calls are bound to the first ChatGPT subject stored in <state_dir>/auth.json.
• The dedicated authenticated Chrome profile is part of the trust boundary for browser subagents.
• agent-commands.yaml can contain sensitive tool inputs. It is gitignored and permission-restricted and should be treated as private.

See SECURITY.md for reporting and scope.

Development

npm run dev
npm run ui:dev
npm run lint
npm run typecheck
npm test
npm run build
npm run ui:build

Run npm run ui:install once after cloning to install the dashboard dependencies. Use npm run inspect for the MCP inspector and npm run schemas to print the published tool schemas. Authenticated browser tests are excluded from CI. See Build and Test.

Documentation

The maintainer wiki contains implementation and operational details:

• Project Overview
• Architecture Map
• Configuration and Startup
• Computer Use
• MCP Tool Surface
• Build and Test
• Open Questions and Risks

Contributing

Read CONTRIBUTING.md before opening a pull request. Run the development validation commands above for code changes.

License

MIT. The vendored apply_patch binary retains its upstream OpenAI Codex license and notices under vendor/apply-patch/.

Shellby MCP is created and maintained by Serbyte Development.