MCP.FileSystem by jihadkhawaja - MCP Server

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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 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.