MCP.FileSystem

A comprehensive Model Context Protocol (MCP) Server that provides powerful file system operations through standardized tools. This server enables AI assistants and other MCP clients to interact with the file system safely and efficiently.

Features

File Operations

• Read/Write Files: Read content from files or create new files with custom content
• Append Content: Add content to existing files without overwriting
• Delete Files: Remove files from the file system
• Copy Files: Duplicate files to new locations
• Move/Rename Files: Relocate or rename files

Directory Operations

• Create Directories: Make new directories with automatic parent creation
• Delete Directories: Remove directories with optional recursive deletion
• List Directory Contents: Browse files and folders with filtering options

Advanced Search Capabilities

• File Name Search: Find files by name patterns with wildcard support
• Content Search: Search for text within files across directories
• Regex Search: Advanced pattern matching using regular expressions
• Recursive Searching: Search through subdirectories

File Information & Utilities

• File Metadata: Get detailed information about files and directories
• Path Validation: Check if files or directories exist
• Directory Size: Calculate total size of directories including subdirectories
• Working Directory: Get and set current working directory

Technology Stack

• .NET 8.0: Built on the latest .NET platform
• C# 12.0: Using modern C# language features
• Model Context Protocol: Implements MCP server specification
• JSON Serialization: Structured responses for easy integration
• Docker Support: Ready for containerized deployment

Installation

Prerequisites

• .NET 8.0 SDK or later
• Compatible MCP client (Claude Desktop, VS Code with MCP extension, etc.)

Building from Source

git clone https://github.com/jihadkhawaja/MCP.FileSystem.git
cd MCP.FileSystem
dotnet build

Running the Server

dotnet run --project MCP.FileSystem

Docker Deployment

docker build -t mcp-filesystem .
docker run -it mcp-filesystem

Usage

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "MCP.FileSystem": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/MCP.FileSystem.csproj"]
    }
  }
}

VS Code with MCP Extension

Configure in your MCP settings:

"servers": {
  "MCP.FileSystem": {
    "type": "stdio",
    "command": "dotnet",
    "args": [
      "run",
      "--project",
      "path/to/MCP.FileSystem.csproj"
    ]
  }
}

Available Tools

File Operations

| Tool | Description | Parameters | |------|-------------|------------| | ReadFile | Read content from a file | filePath | | WriteFile | Write content to a file | filePath, content, overwrite? | | AppendToFile | Append content to a file | filePath, content | | DeleteFile | Delete a file | filePath | | CopyFile | Copy a file | sourcePath, destinationPath, overwrite? | | MoveFile | Move/rename a file | sourcePath, destinationPath, overwrite? |

Directory Operations

| Tool | Description | Parameters | |------|-------------|------------| | CreateDirectory | Create a directory | directoryPath | | DeleteDirectory | Delete a directory | directoryPath, recursive? | | ListDirectory | List directory contents | directoryPath, searchPattern?, includeSubdirectories? |

Search Operations

| Tool | Description | Parameters | |------|-------------|------------| | SearchFiles | Search for files by pattern | directoryPath, searchPattern?, includeSubdirectories?, maxResults? | | SearchInFiles | Search for text in files | directoryPath, searchText, filePattern?, includeSubdirectories?, caseSensitive?, maxResults? | | SearchInFilesRegex | Search using regex patterns | directoryPath, regexPattern, filePattern?, includeSubdirectories?, caseSensitive?, maxResults? |

Information & Utilities

| Tool | Description | Parameters | |------|-------------|------------| | GetFileInfo | Get file/directory metadata | path | | PathExists | Check if path exists | path | | GetCurrentDirectory | Get current working directory | - | | SetCurrentDirectory | Set current working directory | path | | GetDirectorySize | Calculate directory size | directoryPath |

Example Responses

All tools return structured JSON responses:

Success Response

{
  "success": true,
  "message": "File written successfully",
  "path": "/path/to/file.txt",
  "size": 1024
}

Error Response

{
  "error": "File not found",
  "path": "/path/to/nonexistent.txt"
}

Search Results

{
  "success": true,
  "searchPath": "/search/directory",
  "matches": [
    {
      "file": "/path/to/match.txt",
      "fileName": "match.txt",
      "lineNumber": 42,
      "line": "Found matching content here",
      "matchPosition": 6
    }
  ],
  "count": 1,
  "truncated": false
}

Security Considerations

• Path Validation: All file paths are validated to prevent directory traversal attacks
• Error Handling: Comprehensive error handling prevents information leakage
• Permission Respect: Operations respect file system permissions
• Sandboxing: Consider running in a containerized environment for additional security

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Dependencies

• Microsoft.Extensions.Hosting (9.0.7) - Application hosting framework
• ModelContextProtocol (0.3.0-preview.2) - MCP server implementation
• Microsoft.VisualStudio.Azure.Containers.Tools.Targets (1.22.1) - Docker support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v1.0.0

• Initial release with comprehensive file system operations
• Support for file and directory operations
• Advanced search capabilities with regex support
• Docker deployment support
• Complete MCP server implementation

Support

For questions, issues, or contributions, please visit the GitHub repository or open an issue.

Note: This MCP server provides powerful file system access. Ensure you understand the security implications and run it in appropriate environments with proper access controls.