Kavishankarks/your-first-mcp-server

File Operations MCP Server

A Model Context Protocol (MCP) server that provides comprehensive file system operations using FastMCP. This server allows AI assistants to safely interact with the file system through a well-defined set of tools.

Features

The server provides the following file operations:

File Operations

• read_file: Read the contents of a file
• write_file: Write content to a file (creates directories as needed)
• append_file: Append content to an existing file
• delete_file: Delete a file
• copy_file: Copy a file from source to destination
• move_file: Move a file from source to destination

Directory Operations

• list_directory: List contents of a directory with file sizes
• create_directory: Create a directory (including parent directories)
• delete_directory: Delete a directory and all its contents

Information & Search

• get_file_info: Get detailed information about a file or directory
• find_files: Find files matching a pattern in a directory

Installation

🚀 Quick Setup (Recommended)

1. Clone this repository:

git clone <repository-url>
cd your-first-mcp-server

2. Run the setup script:

Linux/macOS:

./setup.sh

Windows (PowerShell):

.\setup.ps1

The setup script will:

• Create a virtual environment
• Install all dependencies
• Configure Claude Desktop automatically
• Create run scripts for easy server management
• Test the installation

3. Restart Claude Desktop to load the new configuration

That's it! The server should now be available in Claude Desktop.

📋 Manual Installation

If you prefer to install manually:

Option 1: Using pip (with virtual environment - recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Option 2: Using pip (system-wide)

pip install -r requirements.txt

Option 3: Using setup.py (development install)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Usage

Running the Server

If you used the setup script:

# Linux/macOS
./run_server.sh           # Regular server
./test_tools.sh           # Run automated tests
./test_tools.sh --interactive  # Interactive testing

# Windows
.\run_server.bat          # Regular server
.\test_tools.bat          # Run automated tests
.\test_tools.bat --interactive  # Interactive testing

Manual start:

# If using virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate
python main.py

# If installed system-wide
python main.py

If you installed using setup.py:

file-operations-server

The server will start and listen for MCP connections.

Using with Claude Desktop

If you used the setup script:

The Claude Desktop configuration is already set up! Just restart Claude Desktop and the server will be available.

Manual Configuration:

If you installed manually, you need to configure Claude Desktop:

1. Copy the example config: Use the provided claude_desktop_config.json file as a starting point
2. Update the path: Edit the file to replace /absolute/path/to/your-first-mcp-server/main.py with the actual absolute path to your server file
3. Copy to Claude config location: Copy the updated config to your Claude Desktop configuration directory

Quick Manual Setup:

# Copy the example config
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Edit the path in the config file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Example configuration:

{
  "mcpServers": {
    "file-operations": {
      "command": "python",
      "args": ["/Users/yourusername/your-first-mcp-server/main.py"]
    }
  }
}

Note: Make sure to use the absolute path to your main.py file.

Configuration File Location

The claude_desktop_config.json file is typically located at:

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

Tool Reference

read_file(path: str) -> str

Reads and returns the contents of a file.

Parameters:

• path: Path to the file to read

Returns: File contents as a string, or error message if file cannot be read.

write_file(path: str, content: str) -> str

Writes content to a file, creating directories as needed.

Parameters:

• path: Path to the file to write
• content: Content to write to the file

Returns: Success message or error message.

append_file(path: str, content: str) -> str

Appends content to an existing file.

Parameters:

• path: Path to the file to append to
• content: Content to append

Returns: Success message or error message.

list_directory(path: str = ".") -> str

Lists the contents of a directory with file sizes and type indicators.

Parameters:

• path: Directory path (defaults to current directory)

Returns: Formatted list of directory contents with 📁 for directories and 📄 for files.

create_directory(path: str) -> str

Creates a directory, including any necessary parent directories.

Parameters:

• path: Directory path to create

Returns: Success message or error message.

delete_file(path: str) -> str

Deletes a file.

Parameters:

• path: Path to the file to delete

Returns: Success message or error message.

delete_directory(path: str) -> str

Deletes a directory and all its contents.

Parameters:

• path: Directory path to delete

Returns: Success message or error message.

copy_file(source: str, destination: str) -> str

Copies a file from source to destination.

Parameters:

• source: Source file path
• destination: Destination file path

Returns: Success message or error message.

move_file(source: str, destination: str) -> str

Moves a file from source to destination.

Parameters:

• source: Source file path
• destination: Destination file path

Returns: Success message or error message.

get_file_info(path: str) -> str

Gets detailed information about a file or directory.

Parameters:

• path: Path to the file or directory

Returns: Formatted information including type, size, modification time, and permissions.

find_files(directory: str = ".", pattern: str = "*") -> str

Finds files matching a pattern in a directory.

Parameters:

• directory: Directory to search in (defaults to current directory)
• pattern: Glob pattern to match (defaults to "*")

Returns: List of matching files and directories.

Error Handling

All tools include comprehensive error handling for common scenarios:

• File not found
• Permission denied
• Invalid paths
• Directory vs file mismatches

Errors are returned as descriptive strings rather than exceptions, making them safe for AI assistant use.

Security Considerations

This server provides full file system access within the permissions of the running process. When deploying:

1. Run with minimal necessary permissions
2. Consider sandboxing the server process
3. Monitor file system access patterns
4. Implement additional access controls as needed for your use case

Development

Testing

To test the server functionality:

# Test basic functionality
python -c "
from main import *
print(list_directory('.'))
print(write_file('test.txt', 'Hello, World!'))
print(read_file('test.txt'))
print(delete_file('test.txt'))
"

Adding New Tools

To add new file operations:

1. Define a new function with the @mcp.tool() decorator
2. Add appropriate error handling
3. Return descriptive success/error messages
4. Update this documentation

License

This project is provided as-is for educational and development purposes.