Local AI Files MCP

Allowlisted local filesystem access for MCP-compatible AI clients.

This project gives desktop AI clients a controlled way to inspect and edit files on your device. It exposes a local MCP server over stdio for desktop clients such as Claude Desktop, and a Streamable HTTP mode for remote/tunneled clients such as ChatGPT custom MCP apps.

What It Can Do

• Show configured allowed folders.
• Inspect file and directory metadata.
• List directories.
• Read UTF-8 text files with byte limits.
• Search text files with optional glob filtering.
• Create, overwrite, or append text files.

The server refuses every path outside explicit allowed roots, resolves real paths to block symlink escapes, and enforces read/write byte limits.

Install

npm install
npm run build

Allow at least one folder:

node dist/cli.js allow ~/Projects

Run With Claude Desktop

Build the project, then add this to Claude Desktop's MCP config, replacing the path:

{
  "mcpServers": {
    "local-ai-files": {
      "command": "node",
      "args": [
        "/home/hemanth/local-ai-files-mcp/dist/cli.js",
        "stdio"
      ]
    }
  }
}

Restart Claude Desktop and ask it to use local-ai-files.

Build Claude Desktop Extension

The included manifest.json follows MCPB manifest version 0.3.

npm run pack:mcpb

That creates local-ai-files-mcp.mcpb. Install it in Claude Desktop through Settings -> Extensions -> Advanced settings -> Install Extension.

Run HTTP Mode For ChatGPT-Style Remote MCP

ChatGPT web cannot connect directly to a local MCP server. Run HTTP mode locally, then expose it through a secure tunnel or OpenAI Secure MCP Tunnel if available for your workspace.

node dist/cli.js http --host 127.0.0.1 --port 3033

MCP endpoint:

http://127.0.0.1:3033/mcp

For ChatGPT custom apps, configure the externally reachable tunnel URL as the MCP server endpoint. Keep the tunnel private, authenticated, and scoped to your own account or workspace.

Commands

local-ai-files-mcp allow <folder>
local-ai-files-mcp deny <folder>
local-ai-files-mcp roots
local-ai-files-mcp stdio [folder...]
local-ai-files-mcp http [folder...] --host 127.0.0.1 --port 3033

Passing folders to stdio or http allows them for that process without changing the saved config.

Security Notes

• Do not allow your whole home folder unless you really want the AI to see it.
• Prefer project-specific folders.
• Treat write_file as a real local write operation.
• Do not expose HTTP mode to the public internet without authentication and network controls.
• Search skips common heavy folders such as .git, node_modules, dist, and build.

Verification

npm run check