file-mcp

<p align="center"> <img src="https://img.shields.io/badge/macOS-12%2B-22293A?style=flat-square&logo=apple&logoColor=white" alt="macOS 12 or later"> <img src="https://img.shields.io/badge/Windows-10%2F11-22293A?style=flat-square&logo=windows&logoColor=white" alt="Windows 10 and 11"> <img src="https://img.shields.io/badge/license-Apache--2.0-DB0F30?style=flat-square" alt="Apache 2.0 license"> <img src="https://img.shields.io/badge/open-source-30394E?style=flat-square" alt="Open source"> </p> <p align="center"> <a href="#quick-start"><strong>Get started</strong></a> · <a href="#highlights">Features</a> · <a href="#security-model">Security</a> · <a href="#development-and-verification">Development</a> </p>

FileMCP is a native macOS and Windows desktop application that gives ChatGPT controlled access to a local workspace through MCP. It can read and modify files, run Git operations, and—only when explicitly enabled—run local shell commands.

The MCP server stays bound to 127.0.0.1. By default, FileMCP uses OpenAI Secure MCP Tunnel to connect supported OpenAI products without a public MCP endpoint. On macOS, you can alternatively use your own Cloudflare Tunnel with a public HTTPS hostname and OAuth. Both options establish an outbound tunnel rather than opening an inbound router port.

[!WARNING] FileMCP can modify or delete files inside the directory you choose. If command execution is enabled, it can also run processes with the permissions of your signed-in OS user. Use a narrowly scoped workspace and enable shell access only when you trust the workflow using it.

FileMCP is an independent open-source project. It is not an official OpenAI product.

Highlights

• Native desktop implementations:
  • Swift + AppKit on macOS.
  • C# + .NET 8 + WPF on Windows.
• Shared core tools on both platforms: filesystem access, Git, Codex-history import, MCP protocol support, OpenAI tunnel integration and optional command execution. Provider choices and permission controls differ; see Application settings.
• Compact macOS interface with a workspace overview, persistent connection controls and a saved light/dark appearance choice.
• Local MCP server listens on loopback only (127.0.0.1).
• Built-in filesystem tools are restricted to one configured workspace root; optional shell commands are not OS-sandboxed.
• Symlink/reparse-point and canonical-path checks protect the workspace boundary.
• Git operations are available without enabling arbitrary shell execution.
• Optional shell execution is off by default.
• Runtime API keys are stored in the operating system credential store:
  • macOS Keychain.
  • Windows Credential Manager.
• Process output, request sizes, search scope, and concurrency are bounded.
• Descendant processes are cleaned up on timeout, stop, and application shutdown.
• Official OpenAI tunnel-client binaries are vendored with documented provenance and checksums.

Screenshots

Current native macOS interface, captured with sample settings and no live connection or real credentials. Cloudflare login status is simulated. Windows uses a separate WPF interface and is not pictured. Click any screenshot to view it at full size.

<table> <tr> <td align="center" valign="top"><strong>Overview</strong><br><a href="assets/screenshots/macos/overview-light.png"><img src="assets/screenshots/macos/overview-light.png" alt="macOS Overview in light appearance showing the sample folder, permissions and connection route" width="290"></a></td> <td align="center" valign="top"><strong>Workspace</strong><br><a href="assets/screenshots/macos/workspace-light.png"><img src="assets/screenshots/macos/workspace-light.png" alt="macOS Workspace in light appearance with file access and optional permissions" width="290"></a></td> </tr> <tr> <td align="center" valign="top"><strong>Connection</strong><br><a href="assets/screenshots/macos/connection-light.png"><img src="assets/screenshots/macos/connection-light.png" alt="macOS Connection in light appearance with OpenAI tunnel ID and runtime API key fields" width="290"></a></td> <td align="center" valign="top"><strong>Activity</strong><br><a href="assets/screenshots/macos/activity-light.png"><img src="assets/screenshots/macos/activity-light.png" alt="macOS Activity in light appearance with the empty log state and persistent Connect action" width="290"></a></td> </tr> </table> <details> <summary>Dark appearance — all four tabs</summary> <table> <tr> <td align="center" valign="top"><strong>Overview</strong><br><a href="assets/screenshots/macos/overview-dark.png"><img src="assets/screenshots/macos/overview-dark.png" alt="macOS Overview in dark appearance showing the sample folder, permissions and connection route" width="290"></a></td> <td align="center" valign="top"><strong>Workspace</strong><br><a href="assets/screenshots/macos/workspace-dark.png"><img src="assets/screenshots/macos/workspace-dark.png" alt="macOS Workspace in dark appearance with file access and optional permissions" width="290"></a></td> </tr> <tr> <td align="center" valign="top"><strong>Connection</strong><br><a href="assets/screenshots/macos/connection-dark.png"><img src="assets/screenshots/macos/connection-dark.png" alt="macOS Connection in dark appearance with OpenAI tunnel ID and runtime API key fields" width="290"></a></td> <td align="center" valign="top"><strong>Activity</strong><br><a href="assets/screenshots/macos/activity-dark.png"><img src="assets/screenshots/macos/activity-dark.png" alt="macOS Activity in dark appearance with the empty log state and persistent Connect action" width="290"></a></td> </tr> </table> </details> <details> <summary>Advanced settings and Cloudflare — light and dark</summary> <table> <tr> <td align="center" valign="top"><strong>Workspace — Advanced options · Light</strong><br><a href="assets/screenshots/macos/workspace-advanced-light.png"><img src="assets/screenshots/macos/workspace-advanced-light.png" alt="Workspace — Advanced options in light appearance" width="290"></a></td> <td align="center" valign="top"><strong>Workspace — Advanced options · Dark</strong><br><a href="assets/screenshots/macos/workspace-advanced-dark.png"><img src="assets/screenshots/macos/workspace-advanced-dark.png" alt="Workspace — Advanced options in dark appearance" width="290"></a></td> </tr> <tr> <td align="center" valign="top"><strong>Cloudflare — dashboard token · Light</strong><br><a href="assets/screenshots/macos/connection-cloudflare-token-light.png"><img src="assets/screenshots/macos/connection-cloudflare-token-light.png" alt="Cloudflare — dashboard token in light appearance" width="290"></a></td> <td align="center" valign="top"><strong>Cloudflare — dashboard token · Dark</strong><br><a href="assets/screenshots/macos/connection-cloudflare-token-dark.png"><img src="assets/screenshots/macos/connection-cloudflare-token-dark.png" alt="Cloudflare — dashboard token in dark appearance" width="290"></a></td> </tr> <tr> <td align="center" valign="top"><strong>Cloudflare — cloudflared login · Light</strong><br><a href="assets/screenshots/macos/connection-cloudflare-login-light.png"><img src="assets/screenshots/macos/connection-cloudflare-login-light.png" alt="Cloudflare — cloudflared login in light appearance" width="290"></a></td> <td align="center" valign="top"><strong>Cloudflare — cloudflared login · Dark</strong><br><a href="assets/screenshots/macos/connection-cloudflare-login-dark.png"><img src="assets/screenshots/macos/connection-cloudflare-login-dark.png" alt="Cloudflare — cloudflared login in dark appearance" width="290"></a></td> </tr> </table> </details>

Use the Dark / Light button beside the app name to switch appearance. Screenshot sources and capture notes are documented in assets/screenshots/README.md.

Platform support

| Platform | App technology | Bundled tunnel-client | Command shell | | --- | --- | --- | --- | | macOS Apple Silicon | Swift / AppKit | darwin-arm64 | User shell (zsh/sh) | | Windows x64 | .NET 8 / WPF | windows-amd64 | Windows PowerShell | | Windows ARM64 | .NET 8 / WPF | windows-arm64 | Windows PowerShell |

The macOS build scripts understand Intel (darwin-amd64), but that platform is not currently bundled in this repository. Add the matching official tunnel-client binary and license sidecar plus the matching official ripgrep binary before building for Intel macOS.

Requirements

For ChatGPT use:

• An account/workspace that permits custom MCP server connections. Availability and administrative permissions depend on the account and workspace; follow OpenAI's current connection guide.
• Git installed if you want to use the built-in Git tools.

Choose one connection provider:

| Provider | Requirements | | --- | --- | | OpenAI Secure MCP Tunnel · macOS and Windows | A tunnel associated with the intended ChatGPT workspace, plus a restricted Platform runtime API key with Tunnels Read + Use. Creating or editing a tunnel requires Tunnels Read + Manage. See the official tunnel guide. | | Cloudflare Tunnel · macOS only | cloudflared, a Cloudflare tunnel and a public HTTPS hostname routed to the local server. Use a dashboard token or a locally authenticated named tunnel. This route does not require an OpenAI tunnel ID or Platform runtime key. |

For development/building:

• macOS: macOS 12 or later and Xcode or Xcode Command Line Tools with swift/swiftc.
• Windows: Windows 10/11 and the .NET 8 SDK. Git for Windows is required for Git-tool verification and normal Git use.

Quick start

macOS

Build:

./build_macos_app.sh

The app is created at:

dist/FileMCP.app

Launch it with:

open "dist/FileMCP.app"

The local build is unsigned. Distribution builds should be code-signed and notarized using the normal macOS release process.

Windows

Build an x64 release from PowerShell:

./build_windows_app.ps1 -Architecture x64

For Windows ARM64:

./build_windows_app.ps1 -Architecture arm64

Release outputs are created under:

dist/windows-x64/FileMCP/
dist/windows-arm64/FileMCP/

and packaged as:

dist/FileMCP-v0.4.0-windows-x64.zip
dist/FileMCP-v0.4.0-windows-arm64.zip

The Windows app is self-contained, so end users do not need to install .NET separately. Local builds are unsigned; production distribution should Authenticode-sign the executable/package.

For a development run on Windows:

./run_windows_dev.ps1

Configure FileMCP

For the default OpenAI provider:

1. Open Connection and enter the Secure MCP Tunnel ID and runtime API key. Saved keys go to macOS Keychain or Windows Credential Manager.
2. Open Workspace on macOS (Settings on Windows) and choose the local folder to share. File tools can read, edit and delete files in that folder; additional permissions are off by default on macOS.
3. Click Connect to save the current configuration and start the local server and tunnel. Wait for Connected, then add it to ChatGPT as described below.

On macOS, Overview summarizes the selected folder, enabled permissions and connection route. Use the top navigation for Workspace, Connection and Activity. The Dark / Light button remembers your appearance choice across launches; before a choice is saved, startup uses the system appearance.

The macOS connection control is available on every tab. Disconnect before changing the pr