File Operations MCP server for AI agents

The File Operations MCP Server provides enhanced file operation capabilities with streaming, patching, and change tracking support through the Model Context Protocol. It offers a comprehensive suite of tools for managing files and directories with built-in security features.

Installation Options

Installing via Smithery

To install File Operations Server for Claude Desktop automatically:

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

Manual Installation

npm install

Docker Installation

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

Transport Modes

Stdio Transport (Default)

For direct integration with MCP clients like Claude Desktop:

npm start

HTTP Transport with SSE

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

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

Rate Limits and Security

The server implements rate limiting to prevent abuse:

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

Path validation prevents directory traversal attacks:

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

Configuration

Environment Variables

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`MCP_HTTP_PORT`	`3001`	Port for HTTP transport

Transport Selection

Stdio: Best for MCP clients like Claude Desktop, direct integration
HTTP: Best for web applications, remote access, development/testing

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-file-operations-server" '{"command":"npx","args":["-y","@bsmi021/mcp-file-operations-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-file-operations-server": {
            "command": "npx",
            "args": [
                "-y",
                "@bsmi021/mcp-file-operations-server"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-file-operations-server": {
            "command": "npx",
            "args": [
                "-y",
                "@bsmi021/mcp-file-operations-server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect