File Operations

You can perform advanced file operations over a flexible MCP interface, including streaming large files, tracking changes, watching directories, and reporting progress. This server empowers you to copy, read, write, move, and delete files and directories with robust security, real-time updates, and scalable HTTP or local stdio integration for your MCP clients.

How to use

Connect to the server using either the local stdio transport for MCP clients or the HTTP transport for web and remote applications. The HTTP interface streams updates via Server-Sent Events and exposes messages through a REST-like API, while the stdio route runs locally for direct client integration.

Key capabilities you can leverage include: performing basic file operations (copy, read, write, move, delete), handling directory operations (create, remove, copy), watching for changes, querying change history, streaming large files, reporting progress in real time, and enforcing security checks like path validation. Use the stdio path for tight coupling with an MCP client, or use the HTTP path when you need remote access or a browser-based client.

Begin by starting the server in your preferred transport mode, then issue operations via your MCP client. For a local development workflow, start the stdio server and connect directly. For a web or remote workflow, start the HTTP server and connect through the provided endpoints.

How to install

# Prerequisites: ensure Node.js is installed (LTS version recommended)
node -v
npm -v

# Development or production setup uses npm
# Development: install dependencies and start in stdio mode by default
npm install
# Start stdio transport
npm start

# Optional: run development server with auto-reload for stdio
npm run dev

# HTTP transport (optional) with auto-reload
npm run dev:http

# Production HTTP start (default stdio is npm start; HTTP start is npm run start:http)
npm run start:http
# If you need a custom port for HTTP
npm run start:http -- --port 8080

Configuration and security notes

{
  "MCP_TRANSPORT": "stdio",             // default: stdio, or "http" for HTTP transport
  "MCP_HTTP_PORT": 3001                   // port used for HTTP transport when enabled
}

Docker usage

# Build the image
docker build -t mcp-file-operations-server .

# Run with stdio transport for MCP clients
docker run -it --rm -v "$(pwd):/workspace" mcp-file-operations-server

# Run with HTTP interface for web/remote access
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http mcp-file-operations-server

Troubleshooting and tips

If you encounter rate limit errors, you will receive a retry-after value with the error message. Ensure your requests stay within the configured limits per tool, resource, and watch operation.

For secure access, verify that all file paths are validated to prevent directory traversal, and ensure input parameters are sanitized before issuing operations.

Available resources and progress

You can monitor resource usage and track progress for long-running operations. Progress updates are delivered as they occur, and a progress token is returned with each operation that supports it.

Available tools

copyFile

Copy a file from a source path to a destination path with optional overwrite control.

readFile

Read and return the contents of a file at a given path.

writeFile

Write content to a file at a specified path, creating the file if it does not exist.

moveFile

Move or rename a file to a new location.

deleteFile

Delete a file at a given path.

appendFile

Append content to an existing file.

makeDirectory

Create a new directory at the specified path.

removeDirectory

Remove a directory and its contents.

copyDirectory

Recursively copy a directory, reporting progress.

watchDirectory

Start watching a directory for changes and emit events on changes.

unwatchDirectory

Stop watching a directory for changes.

getChanges

Retrieve the list of recorded file operation changes.

clearChanges

Clear all recorded changes from the history.