# 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

```bash
npm install
npm run build
```

Allow at least one folder:

```bash
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:

```json
{
  "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`.

```bash
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.

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

MCP endpoint:

```text
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

```bash
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

```bash
npm run check
```