What can you do with this server?

The File Operations MCP Server enables advanced file and directory management with streaming, patching, and change tracking support. * **File Management**: Copy, read, write, move, append, and delete files with options for overwriting and encoding * **Directory Management**: Create, remove, list, and copy directories with recursive capabilities * **Change Monitoring**: Watch directories for changes, unwatch directories, check watching status * **Change Tracking**: Retrieve and clear recorded file system changes with filtering options * **Resource Access**: Access file contents via `file://{path}`, metadata via `metadata://{path}`, directory listings via `directory://{path}`, and recent changes via `file:///recent-changes` * **Progress Reporting**: Track progress of long operations like directory copying * **Security**: Path validation, input sanitization, and rate limiting for safe operations

File Operations MCP Server

A Model Context Protocol (MCP) server that provides enhanced file operation capabilities with streaming, patching, and change tracking support.

Features

Basic File Operations: Copy, read, write, move, and delete files
Directory Operations: Create, remove, and copy directories
File Watching: Monitor files and directories for changes
Change Tracking: Track and query file operation history
Streaming Support: Handle large files efficiently with streaming
HTTP Interface: Streamable HTTP interface with Server-Sent Events (SSE)
Resource Support: Access files and directories through MCP resources
Progress Reporting: Real-time progress updates for long operations
Rate Limiting: Protection against excessive requests
Enhanced Security: Path validation and input sanitization
Robust Error Handling: Comprehensive error handling and reporting
Type Safety: Full TypeScript support with strict type checking
Docker Support: Containerized deployment with volume mounting

Related MCP server: MCP Filesystem Server

Installation

Installing via Smithery

To install File Operations Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude

Manual Installation

npm install

Docker Installation

See DOCKER.md for comprehensive Docker setup instructions including local drive mounting for Windows and Linux.

Quick Docker Start:

# Stdio transport (for MCP clients) docker run -it --rm -v "$(pwd):/workspace" ghcr.io/bsmi021/mcp-file-operations-server # HTTP transport (for web/remote access) docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http ghcr.io/bsmi021/mcp-file-operations-server

Usage

Transport Modes

The server supports two transport modes:

1. Stdio Transport (Default)

For direct integration with MCP clients like Claude Desktop:

npm start

2. HTTP Transport with SSE (New in v1.5)

For remote connections and web applications:

npm run start:http

The HTTP server provides:

SSE Endpoint: GET http://localhost:3001/sse - Establishes streaming connection
Messages Endpoint: POST http://localhost:3001/messages - Receives client messages
Health Check: GET http://localhost:3001/health - Server status
Sessions: GET http://localhost:3001/sessions - Active connection info

Starting the Server

Development Mode

# Stdio transport with auto-reload npm run dev # HTTP transport with auto-reload npm run dev:http

Production Mode

# Stdio transport npm start # HTTP transport npm run start:http # Custom port for HTTP npm run start:http -- --port 8080

Available Tools

Basic File Operations

copy_file: Copy a file to a new location
read_file: Read content from a file
write_file: Write content to a file
move_file: Move/rename a file
delete_file: Delete a file
append_file: Append content to a file

Directory Operations

make_directory: Create a directory
remove_directory: Remove a directory
copy_directory: Copy a directory recursively (with progress reporting)

Watch Operations

watch_directory: Start watching a directory for changes
unwatch_directory: Stop watching a directory

Change Tracking

get_changes: Get the list of recorded changes
clear_changes: Clear all recorded changes

Available Resources

Static Resources

file:///recent-changes: List of recent file system changes

Resource Templates

file://{path}: Access file contents
metadata://{path}: Access file metadata
directory://{path}: List directory contents

Example Usage

Using Stdio Transport (MCP Clients)

// Copy a file await fileOperations.copyFile({ source: 'source.txt', destination: 'destination.txt', overwrite: false }); // Watch a directory await fileOperations.watchDirectory({ path: './watched-dir', recursive: true }); // Access file contents through resource const resource = await mcp.readResource('file:///path/to/file.txt'); console.log(resource.contents[0].text); // Copy directory with progress tracking const result = await fileOperations.copyDirectory({ source: './source-dir', destination: './dest-dir', overwrite: false }); // Progress token in result can be used to track progress console.log(result.progressToken);

Using HTTP Transport (Web/Remote)

Connecting via JavaScript:

// Establish SSE connection const eventSource = new EventSource('http://localhost:3001/sse'); let sessionId = null; eventSource.onopen = function() { console.log('Connected to MCP server'); }; eventSource.onmessage = function(event) { const message = JSON.parse(event.data); // Extract session ID from first message if (!sessionId && message.sessionId) { sessionId = message.sessionId; } console.log('Received:', message); }; // Send a message to the server async function sendMessage(method, params) { const message = { jsonrpc: '2.0', id: Date.now(), method: method, params: params }; const response = await fetch('http://localhost:3001/messages', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Session-ID': sessionId }, body: JSON.stringify(message) }); return response.json(); } // Example: List tools sendMessage('tools/list', {}); // Example: Read a file sendMessage('tools/call', { name: 'read_file', arguments: { path: '/workspace/example.txt' } });

Using curl for testing:

# Start SSE connection in background curl -N http://localhost:3001/sse & # Check server health curl http://localhost:3001/health # List active sessions curl http://localhost:3001/sessions

Interactive Web Client:

A complete interactive example is available at examples/http-client.html. Open this file in a web browser to test the HTTP interface with a user-friendly GUI.

What's New in v1.5

MCP SDK v1.5 Upgrade

Streamable HTTP Interface: New HTTP transport with Server-Sent Events (SSE)
Enhanced API: Upgraded to MCP SDK v1.5 with improved zod-based schemas
Multiple Connections: Support for simultaneous HTTP connections with session management
Better Type Safety: Improved TypeScript integration and error handling

Streaming Features

Large File Support: Efficient streaming for large file operations
Real-time Progress: Progress updates via SSE for long-running operations
Session Management: Multiple client connections with isolated sessions
HTTP API: RESTful endpoints alongside traditional MCP protocol

Docker Support

Quick Start with Docker

# Build the image docker build -t mcp-file-operations-server . # Run with stdio (for MCP clients) docker run -it --rm -v "$(pwd):/workspace" mcp-file-operations-server # Run with HTTP interface docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http mcp-file-operations-server

Volume Mounting

Windows:

docker run -it --rm -v "C:\MyProject:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server

Linux/macOS:

docker run -it --rm -v "/home/user/project:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server

For comprehensive Docker setup instructions including local drive mounting for Windows and Linux, see DOCKER.md.

Rate Limits

The server implements rate limiting to prevent abuse:

Tools: 100 requests per minute
Resources: 200 requests per minute
Watch Operations: 20 operations per minute

Rate limit errors include a retry-after period in the error message.

Security Features

Path Validation

All file paths are validated to prevent directory traversal attacks:

No parent directory references (../)
Proper path normalization
Input sanitization

Resource Protection

Rate limiting on all operations
Proper error handling and logging
Input validation on all parameters
Safe resource cleanup

Progress Reporting

Long-running operations like directory copying provide progress updates:

interface ProgressUpdate { token: string | number; message: string; percentage: number; }

Progress can be tracked through the progress token returned in the operation result.

Development

Building

npm run build

Linting

npm run lint

Formatting

npm run format

Testing

npm test

Configuration

Environment Variables

Variable

Default

Description

MCP_TRANSPORT

stdio

Transport mode: