<div align="center">

📁 High-Performance File System MCP Server

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

---

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
• 🏗️ How It Works (Architecture)
• 🚀 Quick Start Guide
  • 1. Clone Repository
  • 2. Build Docker Image
• 📂 Connecting Files & Folders via MCP
  • Scenario A: Access Desktop Folder Only
  • Scenario B: Access Entire User Directory
  • Scenario C: Access Specific Workspace or Project
  • Scenario D: Access Multiple Folders or Drives
• 💻 Client Integration Guides
  • 1. Claude Desktop
  • 2. Cursor IDE
  • 3. Codex / Continue.dev / VS Code
  • 4. Windsurf / Cline / Roo Code
• 🛠️ Tool Reference & Example Prompts
• 🔧 Local Development (Without Docker)
• ❓ 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

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:

docker build -t file-mcp-server .

Verify that the image is ready:

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:

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:

{
  "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:

     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):

{
  "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):

{
  "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:

# 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!