mishramohit437/file-system-mcp-server

Filesystem MCP Server

A Model Context Protocol (MCP) server that provides secure filesystem operations for AI assistants.

Features

• Read files: Read the contents of text files
• Write files: Create or overwrite files with new content
• List directories: Browse directory contents
• Create directories: Make new directories (with recursive creation)
• Delete files: Remove files from the filesystem
• Rename/move files: Rename files or move them to different locations
• File statistics: Get detailed file/directory metadata
• Path security: Restricts access to explicitly allowed paths only

Installation

1. Clone or create the project:

mkdir filesystem-mcp-server
cd filesystem-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Running the Server

The server requires you to specify allowed paths as command line arguments:

node dist/index.js /path/to/allowed/directory1 /path/to/allowed/directory2

Example:

node dist/index.js /home/user/documents /home/user/projects /tmp

Configuration

To use this server with an MCP client, add it to your client's configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/Users/mohitmishra/Desktop/mcp-for-file-system/dist/index.js",
        "/home/user/documents", 
        "/home/user/projects"
      ]
    }
  }
}

Available Tools

1. read_file

   • Read the contents of a file
   • Parameters: path (string), head (number, optional), tail (number, optional)

2. write_file

   • Write content to a file (overwrites if exists)
   • Parameters: path (string), content (string)

3. move_file

   • Move or rename a file or directory
   • Parameters: source (string), destination (string)

4. create_directory

   • Create a new directory (recursive)
   • Parameters: path (string)

5. list_directory

   • List contents of a directory
   • Parameters: path (string)

6. get_file_info

   • Get file or directory metadata
   • Parameters: path (string)

7. list_allowed_directories

   • List all directories the server is allowed to access
   • No parameters

Security

This server implements path-based security:

• Only paths specified as command line arguments are accessible
• All file operations are restricted to these allowed paths
• Path traversal attempts are blocked
• Paths are resolved to absolute paths to prevent bypassing restrictions

Development

Running in Development Mode

npm run dev /path/to/test/directory

Building

npm run build

Testing

npm test

Error Handling

The server provides detailed error messages for common issues:

• Access Denied: When trying to access files outside allowed paths
• File Not Found: When specified files don't exist
• Permission Errors: When the process lacks necessary file permissions
• Invalid Parameters: When required parameters are missing or invalid

Example Usage

Once configured with an MCP client, you can use natural language to interact with the filesystem:

• "Read the contents of my config.json file"
• "Create a new directory called 'backups' in my documents folder"
• "List all files in the current project directory"
• "Write a TODO list to a new file called tasks.txt"
• "Rename config.json to config-backup.json"
• "Move report.pdf from downloads to documents folder"

Requirements

• Node.js 18.0.0 or higher
• TypeScript 5.0.0 or higher
• @modelcontextprotocol/sdk

License

MIT License - see LICENSE file for details.