LocalBridge

LocalBridge makes the official MCP Filesystem Server's tools available over MCP Streamable HTTP. You can connect an MCP client, such as MCP Inspector or ChatGPT, to read and manage files in directories you explicitly allow.

It preserves 14 filesystem tools, including reading, writing, editing, searching, directory listing, media reads, and moving files. Filesystem restrictions are enforced by the server; they do not depend on client instructions.

Status: The server implements 14 filesystem tools and OAuth. Authenticated Inspector and ChatGPT web listing have been exercised. Full ChatGPT tool coverage, refresh after expiry, desktop interoperability, and POSIX runtime verification remain incomplete.

Requirements

• Node.js 24 LTS and npm. Windows is the locally verified platform; CI is configured for Windows and Ubuntu.

• One or more local directories that you intend to expose to MCP clients.

• To connect remotely: a reachable HTTPS URL that forwards to the LocalBridge HTTP listener and, for OAuth mode, a working OAuth authorization flow.

LocalBridge binds to 127.0.0.1 (normally port 3000). How you securely route HTTPS traffic to that port is a separate deployment decision; the application does not manage your VM, DNS, TLS proxy, or SSH tunnel.

Related MCP server: chatgpt-file-mcp

Install

From a clone of this repository, in PowerShell:

node --version
npm --version
npm ci
npm run build

Run npm run check for typechecking, the production build, and automated tests. Use npm test for tests alone. The repository commits package-lock.json to make dependency installation reproducible.

Configure

Copy the safe templates into private local files:

Copy-Item .env.example .env
Copy-Item config.example.json config.json

1. In config.json, replace the illustrative allowedDirectories path with an existing absolute path to the folder you want to make accessible.

2. Keep the running application, .env, config.json, OAuth database, database sidecars, backups, and private keys outside the allowed roots. LocalBridge refuses roots overlapping application/control state.

3. In .env, set PUBLIC_ORIGIN to your own public HTTPS origin, for example https://mcp.example.com (an example, not a working server). The public MCP endpoint is PUBLIC_ORIGIN + /mcp.

4. Keep AUTH_MODE=oauth for remote usage. It is the default mode. Use a dedicated DATABASE_PATH outside the allowed roots.

Example config.json:

{
  "allowedDirectories": ["D:\\shared-mcp-files"]
}

Create that directory yourself before startup. The provided config.example.json also shows optional request and filesystem resource limits.

PUBLIC_ORIGIN is required in both authentication modes and for auth administration. It must be an HTTPS origin without credentials, a path, a query, or a fragment. Startup fails if it is absent or invalid. Standalone filesystem factories do not require HTTP configuration.

Run with OAuth (recommended for remote access)

Generate one persistent secret, then save it as BETTER_AUTH_SECRET in your private .env:

node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))"

Complete .env with AUTH_MODE=oauth, PUBLIC_ORIGIN, BETTER_AUTH_SECRET, and DATABASE_PATH. For a new auth database, run:

npm run auth:migrate
npm run owner:create
npm start

owner:create prompts locally for the one owner account; it does not open an HTTP listener. The service itself disables public signup. For an existing database, retain its associated secret and signing state; do not recreate the owner or regenerate keys. Stop the running server before migration or other admin commands. A stale <database>.lock after a crash must only be removed after verifying no server/admin process is using that database; do not delete the SQLite DB/WAL/SHM files.

Successful startup reports an endpoint such as http://127.0.0.1:3000/mcp and AUTH_MODE=oauth. Public OAuth discovery endpoints (under /.well-known/) are intentionally accessible without a token; /mcp still requires a valid access token with the files permission.

Optional unauthenticated mode

AUTH_MODE=none is supported to test functionality without OAuth. Everyone who can reach the endpoint can use all 14 tools within the configured directories, including write/edit/move. Neither HTTPS, a loopback listener, Caddy, nor an SSH tunnel authenticates internet callers.

Starting the normal server in this mode additionally requires the exact local acknowledgment:

AUTH_MODE=none
ACK_UNAUTHENTICATED_FILESYSTEM_ACCESS=I_UNDERSTAND_PUBLIC_READ_WRITE_ACCESS

Use disposable allowed folders and avoid exposing no-auth mode on a public URL. Filesystem path and resource-limit checks still apply in both authentication modes.

Connect and test

• MCP Inspector: Start npx -y @modelcontextprotocol/inspector@2.10.1, select Streamable HTTP, and connect to your MCP URL. For OAuth + CIMD, Inspector needs its own publicly reachable HTTPS client metadata document whose callback matches the Inspector session.

• ChatGPT web: Add a custom MCP plugin using your https://<your-domain>/mcp URL, choose OAuth and CIMD, and use ChatGPT's own client document (for the tested setup, https://chatgpt.com/oauth/client.json). Log in as owner and approve the requested files scope; offline_access supports refresh when the client requests and is granted it.

• Manual tool check: Call list_allowed_directories, then list_directory, then read_text_file on a test file. Test writes and moves only on disposable data. Confirm a path outside the allowed root is rejected.

Detailed commands for the VM reverse proxy, Inspector client metadata document, ChatGPT screens, and connection troubleshooting are in the setup and testing guide.

Security and limitations

LocalBridge's root restrictions, symlink/junction checks, size and concurrency budgets reduce risk, but are not a full OS sandbox; hostile concurrent local processes and some filesystem aliases remain outside the protection guarantee. Use least-privilege OS permissions and keep confidential files outside allowed directories. OAuth access tokens are verified as signed JWTs with a 15-minute lifetime. Revocation may not invalidate an already-issued access token immediately; treat it as potentially usable until expiry. Refresh-token rotation allows a 30-second retry overlap.

This software gives remote clients access to real local files. Before authorizing a client, verify your allowed roots and what tools/scopes it will receive.

Development

Run npm run check for strict typechecking, a production build, and the automated suite. Tests use temporary fixtures; platform- or privilege-dependent skips are reported explicitly. The vendored source is required by the tool-contract tests and is excluded from the production build.

Dependency versions are pinned. .npmrc disables dependency install scripts; verify native SQLite loads after a clean installation when changing Node, dependencies, or platforms. Do not suppress compatibility errors with --legacy-peer-deps.

See setup and testing, upstream provenance, and contributor instructions.

License

Original LocalBridge contributions are MIT licensed. Adapted and vendored upstream material retains its upstream licenses; see third-party notices.

No OpenAI developer API key is needed to connect the MCP server through a supported ChatGPT client.