Local Files MCP

English | 日本語

A small local MCP server that lets ChatGPT/Codex read, search, and edit a single allowed folder on this Windows machine through OpenAI Secure MCP Tunnel.

This project is intentionally simple and local-first. The server runs over stdio, and tunnel-client.exe forwards ChatGPT MCP requests to it. The exposed folder is controlled by root-dir.txt, not hardcoded in server.js.

Current folder

This repository lives at:

%USERPROFILE%\mcp-local-files

The folder currently exposed to ChatGPT/Codex is stored in:

%USERPROFILE%\mcp-local-files\root-dir.txt

To see or change it manually:

type %USERPROFILE%\mcp-local-files\root-dir.txt
notepad %USERPROFILE%\mcp-local-files\root-dir.txt

Files

server.js          MCP stdio server implementation
cli.js             npm CLI wrapper and tunnel-client downloader
package.json       Node.js dependencies and npm scripts
run-mcp.cmd        Starts the MCP server using ROOT_DIR from root-dir.txt
mcp-here.cmd       Writes the current terminal directory into root-dir.txt
root-dir.txt       Current allowed folder for Local Files MCP
AGENTS.md          Instructions for Codex/agents working on this folder

Install

From PowerShell:

cd %USERPROFILE%\mcp-local-files
npm install

When installed as an npm package, the CLI command is:

mcp-local-files --help

First-time tunnel setup

The CLI can guide the first tunnel profile setup:

mcp-local-files setup

It will:

download OpenAI tunnel-client if needed
open the OpenAI Tunnels page
open the OpenAI Runtime API keys page
ask for a tunnel_id and Runtime API key
create the default tunnel-client profile
save the Runtime API key outside this project folder

OpenAI setup pages:

https://platform.openai.com/settings/organization/tunnels
https://platform.openai.com/settings/organization/api-keys

The default profile name shown by setup is:

local-files

The Runtime API key is stored in the user's private config file:

%USERPROFILE%\.mcp-local-files\secrets.json

Do not commit this file. It is intentionally outside the npm package folder.

After setup, the profile you just created is saved as the CLI default. That means mcp-local-files --tunnel-here will use that profile automatically unless you pass --profile. If you already ran setup with an older CLI, the command also falls back to the only saved profile when exactly one profile exists.

Non-interactive values can be passed like this:

mcp-local-files setup --profile local-files --tunnel-id tunnel_xxx --no-open

The Runtime API key is still requested interactively so it does not appear in shell history.

On Windows, the default MCP command saved by setup is:

cmd /d /s /c "%USERPROFILE%/mcp-local-files/run-mcp.cmd"

This keeps the existing run-mcp.cmd / root-dir.txt flow intact.

run-mcp.cmd reads ROOT_DIR from root-dir.txt, then exports it to the child node process using the endlocal & set trick so the env var survives across cmd's local scope. server.js resolves ROOT_DIR from, in order:

1. process.env.ROOT_DIR
2. process.argv[2]
3. %USERPROFILE%\mcp-local-files\root-dir.txt

This lets the same run-mcp.cmd work both as the tunnel target and as a local smoke test without changing directory first.

Change the exposed folder quickly

Open Windows Terminal, cd into the folder you want ChatGPT/Codex to access, then run:

%USERPROFILE%\mcp-local-files\mcp-here.cmd

Example:

cd C:\path\to\your-project
%USERPROFILE%\mcp-local-files\mcp-here.cmd

After changing the folder, restart the tunnel client so the new ROOT_DIR is applied.

With the npm CLI, this can be done in one step:

cd C:\path\to\your-project
mcp-local-files --tunnel-here

--tunnel-here writes the current folder to the root file, downloads OpenAI tunnel-client on first use if needed, verifies its SHA256 checksum, and starts the last profile created by mcp-local-files setup.

Use a different profile when needed:

mcp-local-files --tunnel-here --profile local-files

Start the local MCP server directly

For a local smoke test:

cmd /d /s /c "%USERPROFILE%/mcp-local-files/run-mcp.cmd"

The process should keep running. Stop it with Ctrl+C.

The npm CLI can also start the stdio server directly:

mcp-local-files --root C:\path\to\folder

Run through OpenAI Tunnel

The profile already created is:

local-files

Normal run command:

cd C:\path\to\tunnel-client-folder
.\tunnel-client.exe run --profile local-files

The npm CLI can download and run OpenAI tunnel-client automatically:

mcp-local-files tunnel run --profile local-files

If mcp-local-files setup saved a Runtime API key for that profile, the CLI passes it to tunnel-client as CONTROL_PLANE_API_KEY only for the child process.

On first use, it downloads the matching platform zip from the official openai/tunnel-client GitHub release, downloads SHA256SUMS.txt, verifies the archive, extracts the binary into the user cache, and runs it from there.

Default cache locations:

Windows: %USERPROFILE%\.cache\mcp-local-files\tunnel-client
macOS/Linux: ~/.cache/mcp-local-files/tunnel-client

To use an existing binary instead of auto-download:

mcp-local-files --tunnel-client C:\path\to\tunnel-client.exe tunnel run --profile local-files

Useful diagnostic command:

cd C:\path\to\tunnel-client-folder
.\tunnel-client.exe doctor --profile local-files --explain

If the profile must be recreated, prefer forward slashes in the MCP command to avoid Windows escaping problems:

.\tunnel-client.exe init --sample sample_mcp_stdio_local --profile local-files --tunnel-id tunnel_xxx --mcp-command 'cmd /d /s /c "%USERPROFILE%/mcp-local-files/run-mcp.cmd"'

Do not commit or paste Runtime API keys into this project. Set them only in the terminal environment when needed.

The tunnel-client binary is not bundled in this package. It is fetched from OpenAI's public release artifacts when the CLI needs it. Keep the Apache-2.0 LICENSE and OpenAI NOTICE terms in mind if redistributing downloaded artifacts yourself.

Exposed MCP tools

The server registers these tools:

list_files       List files and folders inside ROOT_DIR
read_file        Read UTF-8 text files inside ROOT_DIR
search_files     Search text files inside ROOT_DIR
stat_file        Return metadata for a file or folder inside ROOT_DIR
copy_file        Copy one file inside ROOT_DIR without deleting the source
copy_files       Copy multiple files inside ROOT_DIR without deleting sources
write_file       Create or overwrite UTF-8 text files inside ROOT_DIR
replace_in_file  Replace exact text inside a UTF-8 text file inside ROOT_DIR
read_binary_file_base64  Read a binary file inside ROOT_DIR and return base64
write_base64_file        Decode base64 and write a binary file inside ROOT_DIR

Copy / transfer tools

Use these when you want TransferFiles-style local movement inside the exposed folder. They only copy files inside ROOT_DIR; they do not delete source files and they still block absolute paths or .. escapes.

stat_file input:

{
  "path": "dist/app.zip"
}

copy_file input:

{
  "sourcePath": "dist/app.zip",
  "destinationPath": "incoming/app.zip",
  "overwrite": false
}

copy_files input:

{
  "files": [
    {
      "sourcePath": "dist/app.zip",
      "destinationPath": "incoming/app.zip"
    }
  ],
  "overwrite": false
}

Batch copies are checked before copying starts. Existing destination files are protected unless overwrite is explicitly set to true. Single copied files are capped at 100 MB, and one batch can contain up to 100 files.

Binary file tools

Use these only for files that must be transferred as bytes, such as PNG, JPEG, WebP, GIF, ZIP, or PDF files.

read_binary_file_base64 input:

{
  "path": "images/example.png",
  "maxBytes": 10000000
}

It returns path, size, base64, encoding: "base64", and a simple mimeType guess. If the file is larger than maxBytes, the server returns an error instead of truncating the data.

write_base64_file input:

{
  "path": "images/example.png",
  "base64": "iVBORw0KGgo...",
  "overwrite": false
}

It creates parent folders when needed. Existing files are protected unless overwrite is explicitly set to true. Decoded binary writes are capped at 25 MB.

Safety model

The server is scoped to one folder only. All paths passed to tools must be relative to ROOT_DIR.

The server blocks:

absolute paths
.. path traversal outside ROOT_DIR
text reads for non-allowlisted file types
large text search over files bigger than 2 MB
binary reads above the requested maxBytes limit
binary writes above the server write-size limit
copying files larger than 100 MB
batch copy requests above 100 files

The directory walker skips:

node_modules
.git
.venv

This is intentional. Do not expose C:\, the full user profile, or folders containing secrets unless the user explicitly requests it and understands the risk.

Troubleshooting

If ChatGPT says connector creation failed and the tunnel log shows file already closed, usually the local MCP process exited immediately. Run this first:

cmd /d /s /c "%USERPROFILE%/mcp-local-files/run-mcp.cmd"

If the log says the command is not recognized, check the profile command path. Prefer this form:

cmd /d /s /c "%USERPROFILE%/mcp-local-files/run-mcp.cmd"

If ROOT_DIR is required appears, check run-mcp.cmd and root-dir.txt.

If Node cannot find packages, run:

cd %USERPROFILE%\mcp-local-files
npm install

Notes

Keep the MCP server stdio-clean. Do not print normal logs to stdout from server.js, because stdout is used by the MCP protocol. Use stderr only for critical startup errors.