# Safe Filesystem MCP Server

This MCP server gives AI clients a small, controlled set of filesystem tools. It is designed to work only inside folders you explicitly allow.

## Tools

- `read_file`
- `write_file`
- `create_file`
- `create_directory`
- `rename_file`
- `delete_file`
- `list_directory`
- `search_text`
- `replace_text`
- `run_terminal_command`

## Project Layout

```text
react-dev-mcp/
  config/settings.js    # allowed folders, blocked secret names, terminal rules
  services/             # file, search, and terminal operations
  tools/                # MCP tool registration modules
  utils/                # security, logging, and response helpers
  logs/server.log       # audit log created when tools run
  workspace/            # default folder the AI can access
  server.js             # MCP server entry point
  package.json
```

## Security Rules

The important file is `config/settings.js`.

`workspace.allowedDirectories` controls what the AI can read, write, rename, delete, and search. By default, this server allows its own `workspace` folder and `D:\Development\Projects`.

`workspace.blockedNames` blocks sensitive names such as `.env`, `.npmrc`, and SSH key files even if they are inside an allowed folder.

`run_terminal_command` has extra safeguards:

- runs without a shell, so operators like `;`, `&`, `|`, `<`, `>`, and backticks are rejected
- only runs commands listed in `terminal.allowedCommands`
- runs only inside an allowed folder
- has a timeout and output limit
- receives a small environment instead of your full terminal environment

The terminal allowlist includes common React and React Native commands such as `git`, `node`, `npm`, `npx`, `yarn`, `pnpm`, `bun`, `expo`, `adb`, and `gradlew`. These are powerful because project scripts can run code, so keep client approval enabled for terminal use.

Every tool call is logged to `logs/server.log`. File contents and replacement text are not written to the log; large/sensitive text inputs are recorded as byte counts.

No MCP server can make a bad AI client trustworthy. The secure pattern is: expose only the project folder you want worked on, keep secrets outside allowed folders, review edits before running them, and keep terminal commands allowlisted.

## Install

```bash
npm install
```

## Run

```bash
npm start
```

## Claude Desktop Setup

Add this to Claude Desktop's MCP config, then restart Claude Desktop.

```json
{
  "mcpServers": {
    "safe-filesystem": {
      "command": "node",
      "args": [
        "D:\\Development\\MCP\\react-dev-mcp\\server.js"
      ]
    }
  }
}
```

## ChatGPT Desktop Or Other MCP Clients

Use the same idea in any MCP client:

- command: `node`
- argument: `D:\Development\MCP\react-dev-mcp\server.js`
- transport: stdio

If the client supports per-tool approval, keep approval turned on for write, delete, rename, replace, and terminal tools.

## How To Work Safely

1. Keep this MCP server folder for server code only.
2. Put files the AI may edit inside `workspace` or `D:\Development\Projects`, or add another trusted project folder to `allowedDirectories`.
3. Do not put secrets, private keys, tokens, or production `.env` files in allowed folders.
4. Connect the server from Claude Desktop, ChatGPT Desktop, or another MCP client.
5. Ask the AI to use the tools for file work.
6. Review diffs before running code, committing, or deploying.

## Flow

```text
AI client
  -> asks for an MCP tool
  -> this server validates path, text size, blocked names, and command rules
  -> file or terminal action runs only if validation passes
  -> result returns to the AI client
```

The AI client does not automatically get your full computer through this server. It only gets the tools listed above, and every tool checks the configured safety rules.