# PersonalRemoteMCP

A local-first MCP server for using Desktop Commander tools from local MCP clients or through an authenticated remote HTTP endpoint.

## Features

- File, directory, search, and document operations
- Process and terminal session management
- Tool usage statistics, call history, and local logs
- MCP over stdio and Streamable HTTP
- Optional Cloudflare Access authentication for remote connections

## Requirements

- Windows
- Node.js 22.12 or later
- npm

## Install and build

Run these commands from the project directory:

```powershell
npm ci
npm run build
```

The server stores configuration, history, logs, and cache files in the project-local **data/** directory by default. Set **PERSONAL_REMOTE_MCP_DATA_DIR** to use another writable location.

## Connect a local MCP client

Use stdio mode and point your MCP client to the built entry point:

- Command: **node**
- Arguments: **<project-directory>/dist/index.js**

The client process runs with the permissions of the Windows account that starts it.

## Run the local HTTP endpoint

For local-only use, start the HTTP server with local authentication:

```powershell
$env:PERSONAL_REMOTE_MCP_HTTP_AUTH_MODE = 'local'
$env:PERSONAL_REMOTE_MCP_HTTP_HOST = '127.0.0.1'
$env:PERSONAL_REMOTE_MCP_HTTP_PORT = '8787'
npm run start:http
```

The endpoint is **http://127.0.0.1:8787/mcp**. Local authentication is intended for loopback access only. Do not expose this mode through a public reverse proxy or tunnel.

## Remote access with Cloudflare Access

Remote mode requires Cloudflare Access authentication. The HTTP server continues to listen on loopback; an authenticated ingress forwards requests to it.

1. Create a Cloudflare Access application for the MCP hostname and configure an allow policy for the identities that may use it. Enable MFA where appropriate.
2. Copy **scripts/remote-access/remote-access.env.example** to **data/remote-access.env**.
3. Fill in the Cloudflare team domain, application Audience tag, allowed email address(es), and exact public hostname(s).
4. Build the project with **npm run build**.
5. Start, inspect, or stop the HTTP process with the scripts below.

```powershell
New-Item -ItemType Directory -Force data | Out-Null
Copy-Item scripts/remote-access/remote-access.env.example data/remote-access.env
.\scripts\remote-access\start.ps1 -ValidateOnly
.\scripts\remote-access\start.ps1
.\scripts\remote-access\status.ps1
.\scripts\remote-access\stop.ps1
```

PERSONAL_REMOTE_MCP_CF_ACCESS_ALLOWED_EMAILS accepts one or more comma-separated email addresses. These are the identities permitted by the server-side allowlist; they are not mail-sender settings. Keep **data/remote-access.env** private and never commit real credentials or configuration values.

### If the host has a public IP address

A public IP by itself is not an authenticated deployment. Use a domain proxied through Cloudflare:

- Point a proxied DNS A record at the host's public IP.
- Put a TLS reverse proxy (for example, Caddy or Nginx) on the host and proxy the MCP hostname to **http://127.0.0.1:8787**.
- Preserve the original **Host** header and the **Cf-Access-Jwt-Assertion** header from Cloudflare Access.
- Restrict origin firewall access to Cloudflare's published IP ranges so clients cannot bypass Access by connecting directly to the origin.
- Add the exact hostname to **PERSONAL_REMOTE_MCP_HTTP_ALLOWED_HOSTS**.

### If the host does not have a public IP address

Use Cloudflare Tunnel. The tunnel makes an outbound connection, so the host does not need an inbound public IP or port forwarding:

- Configure a Published application route for the MCP hostname with service URL **http://127.0.0.1:8787**.
- Protect that hostname with the Cloudflare Access application and policy.
- Keep the existing **cloudflared** service running, then start PersonalRemoteMCP with **start.ps1**.

The scripts manage only the PersonalRemoteMCP HTTP process. They do not install, reconfigure, restart, or stop the **cloudflared** service.

## Security notes

- The HTTP listener is restricted to **127.0.0.1**. Remote requests must arrive through an authenticated ingress and pass Cloudflare Access JWT verification and the configured hostname/email allowlists.
- Never expose the unauthenticated **local** authentication mode through a tunnel or public reverse proxy.
- Tools execute with the operating-system permissions of the account running the server. This project is not an OS sandbox; only grant remote access to identities you trust.
- Keep runtime data, environment files, logs, and credentials out of version control.

## License and attribution

See **LICENSE** and **NOTICE** for license and upstream attribution.