mcplocal

Local Files MCP server that lets an MCP-capable client (including ChatGPT Web custom MCP apps where available) read, search and modify files inside one explicitly configured directory.

Features

• Legacy HTTP+SSE: GET /sse + POST /messages
• Modern MCP HTTP endpoint: /mcp
• Health check: /health
• Sandbox: every file path is resolved under MCP_ROOT
• Optional Bearer authentication
• Read/search tools for project discovery
• Write/edit tools for coding workflows
• Delete is disabled by default
• No shell/CLI execution tool
• No dependency on an external database
• Node.js 20+

The MCP TypeScript SDK currently recommends Streamable HTTP for remote servers and treats HTTP+SSE as a backwards-compatibility transport. This project intentionally exposes both so older SSE clients can still connect while newer clients can use /mcp.

1. Run

cp .env.example .env
# edit MCP_ROOT if needed
npm start

Example:

MCP_ROOT=~/Projects
MCP_HOST=127.0.0.1
MCP_PORT=8008
MCP_AUTH_TOKEN=change-me

Then:

SSE:        http://127.0.0.1:8008/sse
Streamable: http://127.0.0.1:8008/mcp
Health:     http://127.0.0.1:8008/health

2. What ChatGPT Web can connect to

ChatGPT Web cannot directly reach localhost from the hosted service. A local MCP server must be made reachable through the supported Secure MCP Tunnel/private-network mechanism. After you have a remote MCP endpoint, add it as a custom MCP app in ChatGPT Developer Mode, scan its tools, and enable it.

For a tunnel that maps the local service, the local origin is:

http://127.0.0.1:8008/sse

or, for modern clients:

http://127.0.0.1:8008/mcp

Do not expose this server to the public internet without authentication and an explicit network policy.

3. Tools exposed to ChatGPT

• list_files(path, recursive)
• read_file(path, startLine, endLine)
• write_file(path, content, createDirs)
• edit_file(path, oldText, newText, replaceAll)
• search_files(query, path, regex, caseSensitive, maxResults)
• create_directory(path)
• file_info(path)
• delete_file(path) only when MCP_ENABLE_DELETE=true

Typical coding workflow:

1. list_files to understand the project.
2. search_files to locate symbols.
3. read_file to inspect the relevant code.
4. edit_file for a surgical change, or write_file for a new file.
5. read_file again to verify the result.

4. Security model

MCP_ROOT is the hard boundary. ../ traversal and absolute paths outside it are rejected. Binary/unreadable files are skipped by search. File size is capped by MCP_MAX_FILE_BYTES.

The server intentionally does not expose arbitrary shell execution. That means ChatGPT can edit code but cannot automatically run rm, curl, package managers, git commands, or arbitrary programs through this MCP.

For a development machine, keep MCP_HOST=127.0.0.1 and use the supported Secure MCP Tunnel rather than binding the server to all interfaces.

5. Build

npm run build
node dist/server.js

The build is dependency-free and copies the runtime into dist/.

6. Docker

docker build -t mcplocal .
docker run --rm -p 8008:8008 -v "$PWD:/workspace" mcplocal

7. Example prompts in ChatGPT

Inspect this local project and tell me where the authentication flow is implemented. Do not modify anything.

Open src/server.js and refactor the error handling. Before changing it, read the relevant code. Then edit only the necessary section and show me what changed.

Search the project for TODO comments and create a report at reports/todos.md.

License

MIT