📁 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.

📑 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

Related MCP server: local-mcp

✨ Core Capabilities

🏗️ 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"
      ]
    }
  }
}

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

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