<div align="center">

# 📁 High-Performance File System MCP Server

### *Secure, Dockerized Model Context Protocol (MCP) Server for File & Directory CRUD Operations*

[![MCP Version](https://img.shields.io/badge/MCP-v1.5.0-blue.svg)](https://modelcontextprotocol.io)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&logoColor=white)](https://www.docker.com/)
[![Node.js](https://img.shields.io/badge/Node.js-v20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

**Empower your AI assistants (Claude Desktop, Cursor, Codex, Windsurf, Continue.dev) to read, write, edit, search, and manage local files and folders seamlessly via Docker Desktop.**

</div>

---

## 📑 Table of Contents

- [✨ Core Capabilities](#-core-capabilities)
- [🏗️ How It Works (Architecture)](#️-how-it-works-architecture)
- [🚀 Quick Start Guide](#-quick-start-guide)
  - [1. Clone Repository](#1-clone-repository)
  - [2. Build Docker Image](#2-build-docker-image)
- [📂 Connecting Files & Folders via MCP](#-connecting-files--folders-via-mcp)
  - [Scenario A: Access Desktop Folder Only](#scenario-a-access-desktop-folder-only)
  - [Scenario B: Access Entire User Directory](#scenario-b-access-entire-user-directory)
  - [Scenario C: Access Specific Workspace or Project](#scenario-c-access-specific-workspace-or-project)
  - [Scenario D: Access Multiple Folders or Drives](#scenario-d-access-multiple-folders-or-drives)
- [💻 Client Integration Guides](#-client-integration-guides)
  - [1. Claude Desktop](#1-claude-desktop)
  - [2. Cursor IDE](#2-cursor-ide)
  - [3. Codex / Continue.dev / VS Code](#3-codex--continuedev--vs-code)
  - [4. Windsurf / Cline / Roo Code](#4-windsurf--cline--roo-code)
- [🛠️ Tool Reference & Example Prompts](#️-tool-reference--example-prompts)
- [🔧 Local Development (Without Docker)](#-local-development-without-docker)
- [❓ Troubleshooting & FAQ](#-troubleshooting--faq)

---

## ✨ Core Capabilities

| Feature | Tool Name | Description |
| :--- | :--- | :--- |
| **Read File** | `read_file` | Read text content of any file within mounted folders. |
| **Read Batch** | `read_multiple_files` | Read multiple files in a single request for fast analysis. |
| **Create / Overwrite** | `write_file` | Create new files or overwrite existing files safely. |
| **Edit & Patch** | `edit_file` | Replace target text blocks (single or `replaceAll` mode). |
| **Delete File** | `delete_file` | Delete specified files from the filesystem. |
| **Create Folder** | `create_directory` | Create recursive directory trees (`mkdir -p`). |
| **List Folder** | `list_directory` | List folder contents with file size, type, & timestamp metadata. |
| **Delete Folder** | `delete_directory` | Remove folders recursively or non-recursively. |
| **Move / Rename** | `move_file` | Move or rename files and directories. |
| **File Metadata** | `get_file_info` | Inspect file stats (size, creation/modified dates, attributes). |
| **Search Files** | `search_files` | Search files via glob patterns (`**/*.ts`, `*.json`), including hidden dotfiles. |

---

## 🏗️ How It Works (Architecture)

```
┌─────────────────────────────────────────────────────────────────┐
│                      AI Client / IDE                            │
│  (Claude Desktop, Cursor, Codex, Windsurf, Continue.dev, etc.)  │
└───────────────────────────────┬─────────────────────────────────┘
                                │ JSON-RPC over Stdio
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Docker Desktop Container                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │               Node.js MCP Server Runtime                  │  │
│  │   - Security validation against allowed directories        │  │
│  │   - Full File & Folder CRUD Operations                    │  │
│  └────────────────────────────┬──────────────────────────────┘  │
└───────────────────────────────┼─────────────────────────────────┘
                                │ Volume Mount (-v)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Host Filesystem                            │
│   (e.g., C:\Users\Username\Desktop  ──>  Mounted as /data)      │
└─────────────────────────────────────────────────────────────────┘
```

> [!SECURITY NOTE]
> **Containerized Isolation**: The AI client can **only** read and modify files in directories explicitly passed to the container via Docker volume mounts (`-v`). Your rest of system remains isolated.

---

## 🚀 Quick Start Guide

### 1. Clone Repository

```bash
git clone https://github.com/SohailShabbir867/file_mcp_server.git
cd file_mcp_server
```

### 2. Build Docker Image

Build the container image tagged as `file-mcp-server`:

```bash
docker build -t file-mcp-server .
```

Verify that the image is ready:

```bash
docker images | grep file-mcp-server
```

---

## 📂 Connecting Files & Folders via MCP

Docker volume mounts (`-v`) control which local folders on your computer are accessible to the AI through the MCP server. Inside the container, mounted paths map to `/data`.

### Scenario A: Access Desktop Folder Only

Mount only your Windows or macOS Desktop folder:

* **Windows**: `-v "C:\Users\YourName\Desktop:/data"`
* **macOS / Linux**: `-v "/Users/yourname/Desktop:/data"`

### Scenario B: Access Entire User Directory

Mount your entire User home folder to allow access to Desktop, Documents, Downloads, Projects, etc.:

* **Windows**: `-v "C:\Users\YourName:/data"`
* **macOS / Linux**: `-v "/Users/yourname:/data"`

### Scenario C: Access Specific Workspace or Project

Mount a specific project directory:

* **Windows**: `-v "D:\Projects\MyApp:/data"`
* **macOS / Linux**: `-v "/Users/yourname/Projects/MyApp:/data"`

### Scenario D: Access Multiple Folders or Drives

You can pass multiple volume mounts to access multiple paths:

```bash
docker run -i --rm \
  -v "C:\Users\YourName\Desktop:/data/desktop" \
  -v "D:\Projects:/data/projects" \
  file-mcp-server /data/desktop /data/projects
```

---

## 💻 Client Integration Guides

### 1. Claude Desktop

#### Configuration File Location:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

#### Config File Example:

Open `claude_desktop_config.json` and add the `file-server` configuration:

```json
{
  "mcpServers": {
    "file-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:\\Users\\Sohail Shabbir\\Desktop:/data",
        "file-mcp-server"
      ]
    }
  }
}
```

> [!TIP]
> **Windows Path Formatting**: Remember to use double backslashes (`\\`) in `claude_desktop_config.json` (e.g. `C:\\Users\\YourName\\Desktop:/data`).
> After updating the file, **restart Claude Desktop**. Look for the hammer icon 🛠️ to confirm tools are loaded!

---

### 2. Cursor IDE

1. Open **Cursor Settings** (`Ctrl + ,` or `Cmd + ,`).
2. Navigate to **Features** -> **MCP Servers**.
3. Click **+ Add New MCP Server**.
4. Set the following fields:
   - **Name**: `file-server`
   - **Type**: `command`
   - **Command**:
     ```bash
     docker run -i --rm -v "C:\Users\Sohail Shabbir\Desktop:/data" file-mcp-server
     ```
5. Click **Save**.

---

### 3. Codex / Continue.dev / VS Code

For **Continue.dev** or VS Code MCP Extensions, add the server to your MCP configuration file (e.g., `~/.continue/config.json` or `.mcp.json`):

```json
{
  "mcpServers": [
    {
      "name": "file-server",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:\\Users\\Sohail Shabbir\\Desktop:/data",
        "file-mcp-server"
      ]
    }
  ]
}
```

---

### 4. Windsurf / Cline / Roo Code

In your extension settings (`cline_mcp_settings.json` or Windsurf MCP settings):

```json
{
  "mcpServers": {
    "file-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:\\Users\\Sohail Shabbir\\Desktop:/data",
        "file-mcp-server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

---

## 🛠️ Tool Reference & Example Prompts

| Tool | Key Parameters | Example Prompt for AI Client |
| :--- | :--- | :--- |
| `read_file` | `path` | *"Read the content of `/data/todo.txt`"* |
| `read_multiple_files`| `paths: [...]` | *"Compare `/data/config.json` and `/data/config.prod.json`"* |
| `write_file` | `path`, `content`, `overwrite` | *"Create a file `/data/notes/ideas.md` with my meeting summary"* |
| `edit_file` | `path`, `target`, `replacement`, `replaceAll` | *"Replace `v1.0.0` with `v1.1.0` in `/data/package.json`"* |
| `delete_file` | `path` | *"Delete temp file `/data/scratch.log`"* |
| `create_directory` | `path` | *"Create folder `/data/projects/new-app/src`"* |
| `list_directory` | `path` | *"List all files and folders inside `/data`"* |
| `delete_directory` | `path`, `recursive` | *"Delete directory `/data/old-builds`"* |
| `move_file` | `source`, `destination` | *"Rename `/data/draft.txt` to `/data/final.txt`"* |
| `get_file_info` | `path` | *"Check creation date and size of `/data/report.pdf`"* |
| `search_files` | `directory`, `pattern` | *"Search for all `.ts` files inside `/data/src`"* |

---

## 🔧 Local Development (Without Docker)

To run or debug the server directly using Node.js:

```bash
# 1. Install dependencies
npm install

# 2. Build TypeScript source
npm run build

# 3. Start server with allowed base directory
node dist/index.js "C:\Users\Sohail Shabbir\Desktop"
```

---

## ❓ Troubleshooting & FAQ

### Q1: `docker: command not found` or connection error
- **Solution**: Ensure **Docker Desktop** is installed and running in your taskbar.

### Q2: Path permission denied inside Claude or Cursor
- **Solution**: Check your `-v` volume mount path. Ensure the directory exists on your computer and your user account has read/write permissions.

### Q3: Cannot find files created by AI
- **Solution**: Files created inside `/data` will appear directly inside the mounted folder on your computer (e.g. `C:\Users\YourName\Desktop`).

---

## 📄 License

This project is licensed under the **MIT License**. Feel free to use, modify, and distribute!