FileSystem MCP Server

A comprehensive Model Context Protocol (MCP) server for advanced file system operations. This server provides structured file management capabilities including file operations, directory management, file watching, search functionality, and archiving operations.

Features

Core File Operations

File Reading: Read files with optional encoding and range support
File Writing: Write content with encoding options and directory creation
File Copying: Copy files with timestamp preservation and overwrite control
File Moving: Move/rename files with conflict resolution
File Deletion: Delete files and directories with recursive options
File Information: Get detailed file metadata including permissions and timestamps

Directory Operations

Directory Creation: Create directories with recursive parent creation
Directory Listing: List contents with filtering, recursion, and depth control
File Finding: Find files using glob patterns with advanced filtering
Directory Size: Calculate directory sizes recursively with human-readable formatting

Advanced Operations

Text Search: Search for patterns in files with context and filtering
File Watching: Watch files and directories for changes with event handling
File Comparison: Compare files with whitespace and case sensitivity options
Archiving: Create and extract archives in multiple formats (ZIP, TAR, GZIP)
Batch Operations: Perform operations on multiple files efficiently

Enterprise Features

TypeScript: Fully typed with comprehensive error handling
Input Validation: Zod schema validation for all parameters
Error Recovery: Graceful error handling with detailed error messages
Resource Management: Automatic cleanup of watchers and resources
Performance: Optimized for large file operations and batch processing

Installation

Clone the repository:

git clone https://github.com/1999AZZAR/filesystem-mcp-server.git
cd filesystem-mcp-server

Install dependencies:

npm install

Build the project:

npm run build

Test the server:

npm start

Configuration

For Cursor IDE

Add this server to your Cursor MCP configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

For Claude Desktop

Add this server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Available Tools

This MCP server provides 18 powerful tools for comprehensive file system management:

1. File Operations

`read_file` - Read File Content

Read file content with optional encoding and range support.

Parameters:

path (required): Path to the file to read
encoding (optional): File encoding - "utf8", "utf16le", "latin1", "base64", "hex", "ascii", "binary" (default: "utf8")
offset (optional): Byte offset to start reading from
limit (optional): Maximum number of bytes to read

Example:

{
  "name": "read_file",
  "arguments": {
    "path": "/path/to/file.txt",
    "encoding": "utf8",
    "offset": 0,
    "limit": 1024
  }
}

Response:

{
  "success": true,
  "message": "File read successfully",
  "path": "/path/to/file.txt",
  "data": {
    "content": "File content here...",
    "encoding": "utf8",
    "size": 1024
  }
}

`write_file` - Write File Content

Write content to file with optional encoding and directory creation.

Parameters:

path (required): Path to the file to write
content (required): Content to write to the file
encoding (optional): File encoding (default: "utf8")
createDirs (optional): Create parent directories if they don't exist (default: false)
append (optional): Append to file instead of overwriting (default: false)

Example:

{
  "name": "write_file",
  "arguments": {
    "path": "/path/to/file.txt",
    "content": "Hello, World!",
    "encoding": "utf8",
    "createDirs": true
  }
}

`copy_file` - Copy File

Copy file from source to destination with options.

Parameters:

source (required): Source file path
destination (required): Destination file path
overwrite (optional): Overwrite destination if it exists (default: false)
preserveTimestamps (optional): Preserve file timestamps (default: true)

Example:

{
  "name": "copy_file",
  "arguments": {
    "source": "/path/to/source.txt",
    "destination": "/path/to/destination.txt",
    "overwrite": true,
    "preserveTimestamps": true
  }
}

`move_file` - Move File

Move file from source to destination.

Parameters:

source (required): Source file path
destination (required): Destination file path
overwrite (optional): Overwrite destination if it exists (default: false)

Example:

{
  "name": "move_file",
  "arguments": {
    "source": "/path/to/source.txt",
    "destination": "/path/to/destination.txt",
    "overwrite": false
  }
}

`delete_file` - Delete File or Directory

Delete file or directory with options.

Parameters:

path (required): Path to delete
recursive (optional): Recursively delete directories (default: false)
force (optional): Force deletion even if path doesn't exist (default: false)

Example:

{
  "name": "delete_file",
  "arguments": {
    "path": "/path/to/file.txt",
    "recursive": false,
    "force": false
  }
}

`get_file_info` - Get File Information

Get detailed file information including metadata.

Parameters:

path (required): Path to get information for
followSymlinks (optional): Follow symbolic links (default: true)

Example:

{
  "name": "get_file_info",
  "arguments": {
    "path": "/path/to/file.txt",
    "followSymlinks": true
  }
}

Response:

{
  "success": true,
  "message": "File information retrieved successfully",
  "path": "/path/to/file.txt",
  "data": {
    "name": "file.txt",
    "path": "/path/to/file.txt",
    "type": "file",
    "size": 1024,
    "isDirectory": false,
    "isFile": true,
    "isSymlink": false,
    "permissions": "644",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "modifiedAt": "2024-01-15T10:30:00.000Z",
    "accessedAt": "2024-01-15T10:30:00.000Z",
    "extension": ".txt",
    "mimeType": "text/plain"
  }
}

2. Directory Operations

`create_directory` - Create Directory

Create directory with optional recursive creation.

Parameters:

path (required): Directory path to create
recursive (optional): Create parent directories recursively (default: false)
mode (optional): Directory permissions in octal format

Example:

{
  "name": "create_directory",
  "arguments": {
    "path": "/path/to/new/directory",
    "recursive": true,
    "mode": "755"
  }
}

`list_directory` - List Directory Contents

List directory contents with optional filtering and recursion.

Parameters:

path (required): Directory path to list
recursive (optional): List contents recursively (default: false)
includeHidden (optional): Include hidden files and directories (default: false)
maxDepth (optional): Maximum depth for recursive listing
fileTypes (optional): Filter by file types - ["file", "directory", "symlink"]

Example:

{
  "name": "list_directory",
  "arguments": {
    "path": "/path/to/directory",
    "recursive": true,
    "includeHidden": false,
    "maxDepth": 3,
    "fileTypes": ["file", "directory"]
  }
}

Response:

{
  "success": true,
  "message": "Directory listed successfully (15 items)",
  "path": "/path/to/directory",
  "data": {
    "items": [
      {
        "name": "file1.txt",
        "path": "/path/to/directory/file1.txt",
        "type": "file",
        "size": 1024,
        "isDirectory": false,
        "isFile": true,
        "isSymlink": false,
        "permissions": "644",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "modifiedAt": "2024-01-15T10:30:00.000Z",
        "accessedAt": "2024-01-15T10:30:00.000Z",
        "extension": ".txt",
        "mimeType": "text/plain"
      }
    ],
    "count": 15,
    "recursive": true,
    "includeHidden": false
  }
}

`find_files` - Find Files

Find files matching a pattern.

Parameters:

pattern (required): Glob pattern to match files
directory (optional): Directory to search in (default: ".")
maxDepth (optional): Maximum search depth
includeHidden (optional): Include hidden files (default: false)
fileTypes (optional): Filter by file types
caseSensitive (optional): Case-sensitive pattern matching (default: false)

Example:

{
  "name": "find_files",
  "arguments": {
    "pattern": "*.txt",
    "directory": "/path/to/search",
    "maxDepth": 3,
    "includeHidden": false,
    "fileTypes": ["file"],
    "caseSensitive": false
  }
}

`get_directory_size` - Get Directory Size

Get directory size recursively.

Parameters:

path (required): Directory path

Example:

{
  "name": "get_directory_size",
  "arguments": {
    "path": "/path/to/directory"
  }
}

Response:

{
  "success": true,
  "message": "Directory size calculated successfully",
  "path": "/path/to/directory",
  "data": {
    "totalSize": 1048576,
    "fileCount": 25,
    "dirCount": 5,
    "humanReadable": "1.00 MB"
  }
}

3. Advanced Operations

`search_in_files` - Search in Files

Search for text patterns in files.

Parameters:

pattern (required): Text pattern to search for
directory (optional): Directory to search in (default: ".")
filePattern (optional): Glob pattern for files to search
maxDepth (optional): Maximum search depth
includeHidden (optional): Include hidden files (default: false)
caseSensitive (optional): Case-sensitive search (default: false)
wholeWord (optional): Match whole words only (default: false)
contextLines (optional): Number of context lines around matches (default: 2)

Example:

{
  "name": "search_in_files",
  "arguments": {
    "pattern": "function",
    "directory": "/path/to/code",
    "filePattern": "*.js",
    "maxDepth": 2,
    "includeHidden": false,
    "caseSensitive": false,
    "wholeWord": true,
    "contextLines": 3
  }
}

Response:

{
  "success": true,
  "message": "Search completed: 5 files with matches",
  "path": "/path/to/code",
  "data": {
    "results": [
      {
        "path": "/path/to/code/file.js",
        "matches": [
          {
            "line": 10,
            "column": 1,
            "text": "function",
            "context": "// This is a function\nexport function myFunction() {\n  return 'hello';\n}"
          }
        ],
        "fileInfo": {
          "name": "file.js",
          "path": "/path/to/code/file.js",
          "type": "file",
          "size": 2048,
          "isDirectory": false,
          "isFile": true,
          "isSymlink": false,
          "permissions": "644",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "modifiedAt": "2024-01-15T10:30:00.000Z",
          "accessedAt": "2024-01-15T10:30:00.000Z",
          "extension": ".js",
          "mimeType": "application/javascript"
        }
      }
    ],
    "totalMatches": 8,
    "pattern": "function",
    "directory": "/path/to/code"
  }
}

`watch_file` - Watch File or Directory

Watch file or directory for changes.

Parameters:

path (required): Path to watch
recursive (optional): Watch recursively (default: false)
ignoreInitial (optional): Ignore initial events (default: true)
ignored (optional): Patterns to ignore

Example:

{
  "name": "watch_file",
  "arguments": {
    "path": "/path/to/watch",
    "recursive": true,
    "ignoreInitial": true,
    "ignored": ["*.tmp", "node_modules/**"]
  }
}

Response:

{
  "success": true,
  "message": "File watching started successfully",
  "path": "/path/to/watch",
  "data": {
    "watching": true,
    "recursive": true,
    "ignoreInitial": true,
    "events": [
      {
        "type": "add",
        "path": "/path/to/watch/newfile.txt",
        "stats": {
          "name": "newfile.txt",
          "path": "/path/to/watch/newfile.txt",
          "type": "file",
          "size": 0,
          "isDirectory": false,
          "isFile": true,
          "isSymlink": false,
          "permissions": "644",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "modifiedAt": "2024-01-15T10:30:00.000Z",
          "accessedAt": "2024-01-15T10:30:00.000Z"
        }
      }
    ]
  }
}

`stop_watching` - Stop Watching

Stop watching a file or directory.

Parameters:

path (required): Path to stop watching

Example:

{
  "name": "stop_watching",
  "arguments": {
    "path": "/path/to/watch"
  }
}

`compare_files` - Compare Files

Compare two files and show differences.

Parameters:

file1 (required): First file path
file2 (required): Second file path
ignoreWhitespace (optional): Ignore whitespace differences (default: false)
ignoreCase (optional): Ignore case differences (default: false)

Example:

{
  "name": "compare_files",
  "arguments": {
    "file1": "/path/to/file1.txt",
    "file2": "/path/to/file2.txt",
    "ignoreWhitespace": true,
    "ignoreCase": false
  }
}

Response:

{
  "success": true,
  "message": "Files differ: 3 differences found",
  "path": "/path/to/file1.txt",
  "data": {
    "identical": false,
    "differences": [
      {
        "line": 5,
        "type": "modified",
        "content": "- old content\n+ new content"
      }
    ],
    "totalDifferences": 3,
    "file1": {
      "path": "/path/to/file1.txt",
      "lines": 10,
      "size": 1024
    },
    "file2": {
      "path": "/path/to/file2.txt",
      "lines": 12,
      "size": 1156
    },
    "options": {
      "ignoreWhitespace": true,
      "ignoreCase": false
    }
  }
}

`archive_files` - Create Archive

Create archive from files.

Parameters:

files (required): Files to archive
archivePath (required): Archive file path
format (optional): Archive format - "zip", "tar", "gzip" (default: "zip")
compressionLevel (optional): Compression level (0-9, default: 6)
includeHidden (optional): Include hidden files (default: false)
excludePatterns (optional): Patterns to exclude

Example:

{
  "name": "archive_files",
  "arguments": {
    "files": ["/path/to/file1.txt", "/path/to/file2.txt"],
    "archivePath": "/path/to/archive.zip",
    "format": "zip",
    "compressionLevel": 6,
    "includeHidden": false,
    "excludePatterns": ["*.tmp"]
  }
}

Response:

{
  "success": true,
  "message": "Archive created successfully",
  "path": "/path/to/archive.zip",
  "data": {
    "archivePath": "/path/to/archive.zip",
    "format": "zip",
    "compressionLevel": 6,
    "size": 2048,
    "filesCount": 2,
    "humanReadable": "2.00 KB"
  }
}

`extract_archive` - Extract Archive

Extract archive to destination.

Parameters:

archivePath (required): Archive file path
destination (required): Extraction destination

Example:

{
  "name": "extract_archive",
  "arguments": {
    "archivePath": "/path/to/archive.zip",
    "destination": "/path/to/extract"
  }
}

Usage Examples

Basic File Operations

// Read a file
const readResult = await mcpClient.callTool('read_file', {
  path: '/path/to/file.txt',
  encoding: 'utf8'
});

// Write a file
const writeResult = await mcpClient.callTool('write_file', {
  path: '/path/to/newfile.txt',
  content: 'Hello, World!',
  createDirs: true
});

// Copy a file
const copyResult = await mcpClient.callTool('copy_file', {
  source: '/path/to/source.txt',
  destination: '/path/to/destination.txt',
  overwrite: true
});

Directory Management

// Create directory
const createDirResult = await mcpClient.callTool('create_directory', {
  path: '/path/to/new/directory',
  recursive: true
});

// List directory contents
const listResult = await mcpClient.callTool('list_directory', {
  path: '/path/to/directory',
  recursive: true,
  includeHidden: false,
  maxDepth: 3
});

// Find files
const findResult = await mcpClient.callTool('find_files', {
  pattern: '*.js',
  directory: '/path/to/code',
  maxDepth: 2,
  fileTypes: ['file']
});

Advanced Operations

// Search in files
const searchResult = await mcpClient.callTool('search_in_files', {
  pattern: 'function',
  directory: '/path/to/code',
  filePattern: '*.js',
  caseSensitive: false,
  wholeWord: true,
  contextLines: 3
});

// Watch for changes
const watchResult = await mcpClient.callTool('watch_file', {
  path: '/path/to/watch',
  recursive: true,
  ignoreInitial: true
});

// Compare files
const compareResult = await mcpClient.callTool('compare_files', {
  file1: '/path/to/file1.txt',
  file2: '/path/to/file2.txt',
  ignoreWhitespace: true
});

// Create archive
const archiveResult = await mcpClient.callTool('archive_files', {
  files: ['/path/to/file1.txt', '/path/to/file2.txt'],
  archivePath: '/path/to/archive.zip',
  format: 'zip',
  compressionLevel: 6
});

Development

Project Structure

filesystem-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server implementation
│   ├── file-operations.ts    # Core file operations
│   ├── directory-operations.ts # Directory management
│   ├── advanced-operations.ts # Advanced features
│   └── types.ts              # Type definitions and schemas
├── dist/                     # Compiled JavaScript output
├── __tests__/               # Test files
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
├── jest.config.js           # Jest testing configuration
└── README.md                # This documentation

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Clean build directory
npm run clean

# Start production server
npm start

Testing

The server includes comprehensive Jest tests:

npm test

Test Coverage:

File operations (read, write, copy, move, delete)
Directory operations (create, list, find)
Advanced operations (search, watch, compare, archive)
Error handling and edge cases
Input validation and schema validation

Error Handling

The server includes comprehensive error handling:

Input Validation: All parameters validated with Zod schemas
File System Errors: Graceful handling of permission, not found, and access errors
Resource Cleanup: Automatic cleanup of watchers and resources
Process Management: Proper signal handling for graceful shutdown

Performance Considerations

Streaming: Large file operations use streaming for memory efficiency
Batch Operations: Multiple file operations optimized for performance
Caching: File information cached for repeated operations
Resource Management: Automatic cleanup prevents memory leaks

Security Considerations

Path Validation: All paths validated to prevent directory traversal attacks
Permission Checks: File operations respect system permissions
Input Sanitization: All inputs validated and sanitized
Error Information: Error messages don't expose sensitive information

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: npm test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Support

For issues and questions:

GitHub Issues: Open an issue
Documentation: Check this README for comprehensive usage examples
Examples: See the examples section above for common use cases

FileSystem MCP Server - Comprehensive file system operations for the Model Context Protocol ecosystem.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
__tests__		__tests__
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
example-config.json		example-config.json
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
test-demo.txt		test-demo.txt
tsconfig.json		tsconfig.json

License

1999AZZAR/filesystem-mcp-server

Folders and files

Latest commit

History

Repository files navigation

FileSystem MCP Server

Features

Core File Operations

Directory Operations

Advanced Operations

Enterprise Features

Installation

Configuration

For Cursor IDE

For Claude Desktop

Available Tools

1. File Operations

read_file - Read File Content

write_file - Write File Content

copy_file - Copy File

move_file - Move File

delete_file - Delete File or Directory

get_file_info - Get File Information

2. Directory Operations

create_directory - Create Directory

list_directory - List Directory Contents

find_files - Find Files

get_directory_size - Get Directory Size

3. Advanced Operations

search_in_files - Search in Files

watch_file - Watch File or Directory

stop_watching - Stop Watching

compare_files - Compare Files

archive_files - Create Archive

extract_archive - Extract Archive

Usage Examples

Basic File Operations

Directory Management

Advanced Operations

Development

Project Structure

Development Commands

Testing

Error Handling

Performance Considerations

Security Considerations

License

Contributing

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`read_file` - Read File Content

`write_file` - Write File Content

`copy_file` - Copy File

`move_file` - Move File

`delete_file` - Delete File or Directory

`get_file_info` - Get File Information

`create_directory` - Create Directory

`list_directory` - List Directory Contents

`find_files` - Find Files

`get_directory_size` - Get Directory Size

`search_in_files` - Search in Files

`watch_file` - Watch File or Directory

`stop_watching` - Stop Watching

`compare_files` - Compare Files

`archive_files` - Create Archive

`extract_archive` - Extract Archive

Packages