Local-File-Operation-MCP-Server by DawidNowak - MCP Server

Local Files MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to safely interact with your local file system. Built with C# .NET 8.0, this server provides secure file operations within your home directory, allowing Claude to read, write, list, and manage files directly on your computer.

🤖 What is this?

This MCP server bridges the gap between Claude Desktop (Anthropic's desktop application) and your local file system. Once configured, you can ask Claude to:

"List all files in my Documents folder"
"Read the contents of my project's README file"
"Create a new Python script called hello.py"
"Delete the temporary files in my Downloads folder"

The server uses the Model Context Protocol, a standardized way for AI assistants to securely access external resources. It communicates with Claude Desktop through JSON-RPC 2.0 over stdin/stdout, providing a secure sandbox that restricts all operations to your home directory.

🌟 Features

🔒 Secure: All operations restricted to your home directory
📁 File Browsing: List files and directories with detailed metadata
📖 File Reading: Read text files with encoding detection and size limits
✏️ File Writing: Create and edit files with atomic write operations
🗑️ File Deletion: Remove files and directories with safety checks
🛡️ Safety First: Binary file detection, size limits, path validation

🚀 Quick Start

Prerequisites

.NET 8.0 SDK or later
Windows, macOS, or Linux

Installation

Option 1: Automated Setup (Recommended)

Clone the repository:

git clone https://github.com/your-username/local-files-mcp-server.git
cd local-files-mcp-server

Run the setup script:
```
.\setup.ps1
```
This will:
- Build and publish the MCP server
- Automatically configure Claude Desktop
- Create the necessary configuration files
Restart Claude Desktop and look for "✅ local-files: connected"

💡 Tip: You can verify the MCP server connection status in Claude Desktop by going to Settings → Developer where you'll see all configured MCP servers and their connection status.

Option 2: Manual Setup

Clone and build:

git clone https://github.com/your-username/local-files-mcp-server.git
cd local-files-mcp-server
dotnet build

For Claude Desktop integration:
- Publish the executable: dotnet publish -c Release -o publish --self-contained true -r win-x64 /p:PublishSingleFile=true
- Copy claude_desktop_config.json to %APPDATA%\Claude\claude_desktop_config.json
- Edit the config file to replace PATH_TO_REPO with your actual repository path
- Restart Claude Desktop

For direct usage:

dotnet run --project LocalFilesMcpServer

The server communicates via stdin/stdout using JSON-RPC 2.0 protocol.

� Screenshots

See the MCP server in action with Claude Desktop:

- Creating new directories through Claude Desktop
- Browsing directory contents with detailed metadata
- Creating new files with custom content
- Reading and analyzing file contents
- Removing directories and cleaning up

These screenshots demonstrate the complete file management workflow available through Claude Desktop integration.

�📋 Available Tools

1. `list_files` - Browse Directory Contents

Lists files and directories with metadata

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "path": "Documents"
    }
  }
}

2. `read_file` - Read File Contents

Reads text files up to 50MB

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "Documents/example.txt"
    }
  }
}

3. `write_file` - Create/Edit Files

Writes content to files with atomic operations

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "Documents/new_file.txt",
      "content": "Hello, World!\nThis is a new file."
    }
  }
}

4. `delete_file` - Remove Files/Directories

Deletes files or directories (recursive for directories)

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "delete_file",
    "arguments": {
      "path": "Documents/old_file.txt"
    }
  }
}

🔧 Usage Examples

Complete Workflow Example

# Initialize MCP session
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0.0"}}}' | dotnet run --project LocalFilesMcpServer

# List available tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | dotnet run --project LocalFilesMcpServer

# Browse files in Documents folder
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_files","arguments":{"path":"Documents"}}}' | dotnet run --project LocalFilesMcpServer

Interactive Testing

Create a test script (test_session.txt):

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_files","arguments":{"path":"."}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"write_file","arguments":{"path":"test.txt","content":"Hello MCP!"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"test.txt"}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"delete_file","arguments":{"path":"test.txt"}}}

Run it:

type test_session.txt | dotnet run --project LocalFilesMcpServer

🛡️ Security Features

Home Directory Restriction: All paths are resolved relative to your home directory
Path Validation: Prevents directory traversal attacks (e.g., ../../../etc/passwd)
File Size Limits: Reading limited to 50MB, writing limited to 50MB
Binary File Detection: Automatically detects and refuses to read binary files
Permission Checking: Validates read/write permissions before operations
Atomic Writes: Files are written atomically (temp file + move) to prevent corruption

📁 Project Structure

LocalFilesMcpServer/
├── Models/             # MCP protocol message models
│   ├── McpMessage.cs   # Base JSON-RPC 2.0 classes
│   ├── InitializeMessage.cs
│   ├── ToolMessage.cs
│   ├── CallToolMessage.cs
│   ├── Tool.cs
│   └── FileItem.cs
├── Services/           # Core business logic
│   ├── McpProtocolHandler.cs   # MCP protocol routing
│   ├── FileOperationService.cs # File system operations
│   └── PathValidationService.cs # Security validation
├── Tools/              # Individual tool implementations
│   ├── ListFilesTool.cs
│   ├── ReadFileTool.cs
│   ├── WriteFileTool.cs
│   └── DeleteFileTool.cs
└── Program.cs          # Application entry point

🔍 Error Handling

The server provides detailed error messages following MCP error codes:

-32700: Parse error (malformed JSON)
-32600: Invalid Request
-32601: Method not found
-32602: Invalid parameters
-32603: Internal error
-32002: Server not initialized

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Error: File not found. Action: Provide a valid file path for file access"
  }
}

🧪 Development

Building & Testing

# Build the project
dotnet build

# Run all tests (when implemented)
dotnet test

# Check code formatting
dotnet format --verify-no-changes

📖 MCP Protocol

This server implements the Model Context Protocol specification:

Protocol Versions: 2024-11-05 and 2025-06-18 (multi-version support for compatibility)
Transport: stdio (stdin/stdout)
Message Format: JSON-RPC 2.0
Capabilities: Tools (file operations)

📝 License

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

Happy file managing with Claude! 🚀