Remote MCP (alpha)

An owner-controlled, local MCP server for authorized file operations, read-only Git inspection, and preconfigured process execution. Designed for an Apple Silicon Mac and a later secure relay, without pretending that directory restrictions constitute a shell sandbox.

Status: pre-release local prototype under the MIT License. MCP tool calls have been tested with a real MCP client in an isolated test directory. ChatGPT remote access, macOS lifecycle, and SaaS are not yet verified or shipped.

Quick start (macOS, Node.js 22+)

git clone https://github.com/karkandea/remote-mcp.git
cd remote-mcp
npm ci
npm run check
npm run build
node dist/cli.js init
node dist/cli.js doctor

Public source: karkandea/remote-mcp. When using a local source archive, extract it and start at npm ci.

Edit ~/.config/remote-mcp/config.json with a small test directory first. See config.example.json. The default configuration authorizes no directory, no writes, and no commands.

deniedNames only adds exclusions. Sensitive names including .ssh, .aws, .env, .git, .npmrc, .netrc, and .kube are always denied, even if the custom list is empty. This is a defense-in-depth filter, not a guarantee against every secret or filesystem race.

node dist/cli.js start

start speaks MCP over stdio, so run it from an MCP host or compatible client. It does not run an HTTP server or open a public port. It must not write regular logs to stdout while serving MCP.

Local lifecycle commands:

The stop command does not independently kill a host-owned stdio process; the host still controls its lifecycle. doctor reports localAccessEnabled, not whether ChatGPT or a remote client is connected. A launchd service, menu-bar UI, and automatic reconnection have not been implemented yet.

Related MCP server: fsguard-mcp

Capabilities

The terminal tool takes a profile name, not a shell script. For example, the sample-tests profile in the configuration invokes exactly /usr/bin/true in the sample directory. To allow project tests, a user must consciously add a command profile with an executable, fixed arguments, and an authorized working directory. Those commands are still capable of reading or writing outside approved roots when the operating system permits it. Never configure a broad shell profile, unreviewed scripts, or production credentials.

Connect with MCP clients

For local clients that support stdio servers, point the client to the absolute Node executable and the absolute path to dist/cli.js with argument start (or use a client configuration that invokes node via PATH). Set the child's current account to the non-root Mac user who owns the config. The client must not be configured to auto-approve dangerous tools.

Remote ChatGPT integration is a separate milestone: evaluate OpenAI Secure MCP Tunnel only where the owner's workspace and Platform organization have the required permissions. Do not expose a raw stdio-to-HTTP proxy or a terminal endpoint to the internet without authentication and authorization.

Development

npm run typecheck
npm test
npm run build

Tests use synthetic temporary directories, not personal repositories. The MCP tests cover in-memory tool discovery, real disk reads, post-disconnect denial, and a separate real stdio subprocess handshake. Process tests execute a fixed Node test command.

Docs

• Architecture and future relay

• Security model

• Roadmap and acceptance criteria

• VPS-only CI policy

• Dedicated VPS CI runner deployment

• Mac verification checkpoint

• Contributing

• Changelog

• MIT License

Important limitations

• The local prototype runs under the privileges of the user launching it. It is not a filesystem or process sandbox.

• No interactive trusted owner-approval UI exists yet; therefore, only preauthorized command profiles are exposed. High-risk arbitrary commands are not supported.

• Symlink checks and atomic file replacement reduce common errors but cannot eliminate all filesystem race conditions.

• No remote authentication, device pairing, outbound relay, token storage, launchd integration, or SaaS tenancy exists in this release.

• GitHub Actions are prohibited for this project. scripts/ci.sh is verified on the owner's VPS; the independent main-only CI poller and systemd timer are implemented in source but not deployed. Public PRs are not executed yet.

• macOS installation and full ChatGPT-to-Mac end-to-end demonstration remain outstanding.

Do not use this alpha on a privileged, company-managed, or production workstation.