MCP Filesystem Server

An MCP (Model Context Protocol) server for filesystem operations with built-in security features.

Features

• File Reading: Read text file contents

• File Writing: Create or overwrite files

• Directory Listing: List contents with details (name, type, size, modified date)

• File Search: Search for files using regex patterns

• File Information: Get detailed metadata for files/directories

• Directory Creation: Create new directories

• File Deletion: Delete files and directories (Downloads folder only for safety)

Related MCP server: File System MCP Server

Security

The server implements the following security measures:

1. Allowed Directories: Only allows access to specific directories:

   • ~/Documents

   • ~/Downloads

2. Delete Restrictions: Delete operations are only allowed in ~/Downloads folder for safety

3. Path Validation: Prevents path traversal attacks

4. Size Limits: Files limited to 10MB for read operations

5. Depth Limits: Searches limited to 5 levels deep by default

Installation

# Install dependencies
npm install

# Compile TypeScript
npm run build

Usage

As a standalone MCP server

npm start

Integration with Claude Desktop

1. Build the project:

npm run build

2. Update your Claude Desktop configuration at:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

3. Add the server configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-test/dist/index.js"]
    }
  }
}

4. Restart Claude Desktop

Available Tools

read_file

Reads the contents of a file.

Parameters:

• path (string): Path to the file to read

Example:

{
  "path": "~/Documents/test.txt"
}

write_file

Writes content to a file.

Parameters:

• path (string): Path to the file

• content (string): Content to write

Example:

{
  "path": "~/Documents/test.txt",
  "content": "Hello, World!"
}

list_directory

Lists directory contents with details.

Parameters:

• path (string): Path to the directory

Example:

{
  "path": "~/Documents"
}

search_files

Searches for files matching a regex pattern.

Parameters:

• directory (string): Directory to search in (must be within allowed directories)

• pattern (string): Regex pattern to match file names

• maxDepth (number, optional): Maximum search depth (default: 5)

Example:

{
  "directory": "~/Documents",
  "pattern": "\\.txt$",
  "maxDepth": 3
}

get_file_info

Gets detailed information about a file or directory.

Parameters:

• path (string): Path to the file or directory

Example:

{
  "path": "~/Documents/test.txt"
}

create_directory

Creates a new directory.

Parameters:

• path (string): Path to the directory to create

Example:

{
  "path": "~/Documents/new-folder"
}

delete_file

Deletes a file or directory. Only works in Downloads folder for safety.

Parameters:

• path (string): Path to the file or directory to delete (must be in Downloads)

• recursive (boolean, optional): If true, delete directories and their contents recursively (default: false)

Examples:

Delete a file:

{
  "path": "~/Downloads/old-file.txt"
}

Delete a directory and its contents:

{
  "path": "~/Downloads/temp-folder",
  "recursive": true
}

Important Notes:

• Delete operations are only allowed in the Downloads folder

• Attempting to delete files in Documents or other locations will be denied

• Directories require recursive: true parameter to be deleted

• Deleted files cannot be recovered

Development

# Compile in watch mode
npm run watch

# Compile once
npm run build

# Run after compiling
npm start

Project Structure

MCP-test/
├── src/
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled files (generated)
├── package.json
├── tsconfig.json
├── config.example.json   # Configuration example
└── README.md

Customization

To change allowed directories, edit the ALLOWED_DIRECTORIES constant in src/index.ts:

const ALLOWED_DIRECTORIES = [
  path.join(os.homedir(), "Documents"),
  path.join(os.homedir(), "Downloads"),
  // Add more directories here
];

To change the file size limit:

const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

Troubleshooting

Server doesn't start

• Verify you've compiled the project with npm run build

• Verify the path in the configuration is absolute and correct

"Access denied" when trying to access a file

• Verify the file is within ~/Documents or ~/Downloads

• Check file permissions

"File too large"

• Files are limited to 10MB by default

• Modify MAX_FILE_SIZE if you need larger files

License

MIT