MCP 服务器

High-Performance File System MCP Server

A secure, Dockerized MCP server enabling AI assistants to perform file and directory CRUD operations like read, write, edit, search, and manage local files via natural language.

README

📁 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
💻 Client Integration Guides
🛠️ 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

Open Cursor Settings (Ctrl + , or Cmd + ,).
Navigate to Features -> MCP Servers.
Click + Add New MCP Server.

Set the following fields:

Name: file-server
Type: command

Command:

docker run -i --rm -v "C:\Users\Sohail Shabbir\Desktop:/data" file-mcp-server

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!