# Python MCP Filesystem Server

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-2.0.0-green.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A comprehensive **Model Context Protocol (MCP)** server that provides AI assistants with secure, controlled filesystem access. Built with Python for easy customization and learning.

## Overview

This MCP server enables AI assistants like Claude to interact with your filesystem through a secure, sandboxed interface. It provides 14 powerful tools for file operations, from basic read/write to advanced features like content search and directory tree visualization.

## Features

### 📁 File Operations
- **read_file** - Read file contents
- **write_file** - Create or overwrite files
- **append_file** - Append to existing files
- **delete_file** - Delete files

### 📂 Directory Operations
- **list_files** - List directory contents
- **list_directory_tree** - Visualize directory structure
- **create_directory** - Create new directories
- **delete_directory** - Delete directories recursively

### 🔍 Search & Discovery
- **search_files** - Find files by name pattern (wildcards)
- **search_content** - Search text within files
- **file_exists** - Check file/directory existence
- **get_file_info** - Get metadata (size, dates, type)

### 🔧 File Management
- **rename_file** - Rename files/directories
- **move_file** - Move files/directories

### 🔒 Security Features
- **Path validation** - Prevents directory traversal attacks
- **Workspace sandboxing** - All operations restricted to designated directory
- **Error handling** - Comprehensive error messages for all operations

---

## Quick Start

### Prerequisites
- Python 3.10 or higher
- pip package manager

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/YOUR-USERNAME/mcp-filesystem-server-python.git
   cd mcp-filesystem-server-python
   ```

2. **Create virtual environment**
   ```bash
   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # macOS/Linux
   source venv/bin/activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Test the server** (optional)
   ```bash
   python examples/demo.py
   ```

---

## Configuration

### Claude Desktop Setup

Add this configuration to Claude Desktop:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["C:\\path\\to\\mcp-filesystem-server-python\\src\\server.py"],
      "env": {
        "WORKSPACE_DIR": "C:\\path\\to\\your\\workspace"
      }
    }
  }
}
```

**Important:** 
- Use absolute paths
- On Windows, use double backslashes (`\\`) or forward slashes (`/`)
- Set `WORKSPACE_DIR` to the directory you want Claude to access

### Windows Store Claude Desktop

If using Windows Store version, use this location instead:
```
%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
```

---

## Usage Examples

### Basic File Operations

**Ask Claude:**
```
"List files in my workspace"
```

**Claude will use:** `list_files` tool

---

**Ask Claude:**
```
"Read the file report.txt"
```

**Claude will use:** `read_file` tool with path: `"report.txt"`

---

**Ask Claude:**
```
"Create a file called notes.txt with a bullet list of my tasks"
```

**Claude will use:** `write_file` tool

---

### Advanced Operations

**Search for files:**
```
"Find all Python files in my workspace"
```
Uses: `search_files` with pattern `"*.py"`

---

**Search content:**
```
"Which files contain the word 'TODO'?"
```
Uses: `search_content` with text `"TODO"`

---

**Directory tree:**
```
"Show me the structure of my workspace"
```
Uses: `list_directory_tree`

---

**File metadata:**
```
"Get information about config.json"
```
Uses: `get_file_info` with path `"config.json"`

---

## Project Structure

```
mcp-filesystem-server-python/
├── src/
│   └── server.py          # Main MCP server implementation
├── examples/
│   └── demo.py            # Standalone demo (test without Claude)
├── requirements.txt       # Python dependencies
├── README.md              # This file
├── LICENSE                # MIT License
└── .gitignore            # Git exclusions
```

---

## Development

### Running Standalone

Test the server without Claude Desktop:

```bash
python examples/demo.py
```

This simulates how Claude would interact with your server.

### Manual Testing

Start the server manually to see debug output:

```bash
# Windows
set WORKSPACE_DIR=C:\path\to\workspace
python src\server.py

# macOS/Linux
WORKSPACE_DIR=/path/to/workspace python src/server.py
```

The server communicates via stdio and expects MCP protocol messages.

### Adding New Tools

1. Add tool definition in `handle_list_tools()` function
2. Implement handler in `handle_call_tool()` function
3. Follow existing patterns for error handling
4. Test with `examples/demo.py`

---

## How MCP Works

### Architecture

```
┌─────────────────┐          ┌──────────────────┐
│  Claude Desktop │ ◄──────► │   MCP Server     │
│    (Client)     │   stdio  │  (src/server.py) │
└─────────────────┘          └──────────────────┘
                                      │
                                      ▼
                             ┌─────────────────┐
                             │  Your Workspace │
                             │     (Files)     │
                             └─────────────────┘
```

### Communication Flow

1. **Claude starts your server** → Python process launches
2. **Claude asks:** "What tools do you have?" → `handle_list_tools()`
3. **Your server responds** → List of 14 tools
4. **User requests action** → "List my files"
5. **Claude calls tool** → `handle_call_tool(name="list_files", ...)`
6. **Your server executes** → Reads directory, returns results
7. **Claude shows results** → User sees file list

### Key Concepts

- **stdio transport** - Communication via standard input/output
- **Tools** - Functions Claude can call with JSON parameters
- **Handlers** - Your Python functions that implement tools
- **Types** - MCP protocol message types (`Tool`, `CallToolResult`, etc.)

---

## Troubleshooting

### Claude doesn't see the tools

1. Check config file path is correct
2. Verify Python path in config is absolute
3. Restart Claude Desktop completely
4. Check Claude Desktop version supports MCP (requires Pro)

### "Access denied" errors

- Ensure `WORKSPACE_DIR` is set correctly
- Check file/directory permissions
- Verify paths are within workspace (security feature)

### Server not starting

- Test Python path: Run the command from config manually
- Check dependencies: `pip install -r requirements.txt`
- Verify Python version: `python --version` (need 3.10+)

### Finding logs

Windows Store version logs may be in:
```
%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\
```

---

## Contributing

Contributions welcome! This is a learning-friendly project.

### Ideas for improvements:
- Add file copy tool
- Add archive/zip tools
- Add file watching/monitoring
- Add binary file support
- Add permission management
- More sophisticated search (regex)

---

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop](https://claude.ai/download)

---

## Acknowledgments

Built as a learning project to understand the Model Context Protocol. Perfect for:
- Learning MCP server development
- Understanding AI-filesystem interaction
- Building custom AI tools
- Educational purposes

---

**Questions or issues?** Open an issue on GitHub!
}
```

**macOS/Linux:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/file-system-server-python/src/server.py"],
      "env": {
        "WORKSPACE_DIR": "/path/to/test-workspace"
      }
    }
  }
}
```

Then restart Claude Desktop and ask it to:
- "List the files in my workspace"
- "Read sample.txt"
- "Create a new file called notes.txt with some content"

### Option 2: Debug in VS Code

1. Open this project in VS Code
2. Install the Python extension
3. Press **F5** or go to **Run > Start Debugging**
4. The server starts in debug mode - you can set breakpoints in [src/server.py](src/server.py)

## Project Structure

```
file-system-server-python/
├── src/
│   └── server.py         # Main server implementation (READ THIS!)
├── requirements.txt      # Python dependencies
├── .vscode/
│   ├── launch.json      # VS Code debug configuration
│   └── mcp.json         # VS Code MCP debug config
└── README.md            # This file
```

## Understanding the Code

Open [src/server.py](src/server.py) and you'll see:

### 1. Server Creation (line ~27)

```python
server = Server("simple-filesystem-server")
```

### 2. Input Validation with Pydantic (lines ~30-40)

```python
class ReadFileInput(BaseModel):
    path: str = Field(description="Relative path to file")
```

Pydantic validates inputs automatically, similar to Zod in TypeScript.

### 3. Tool Registration with Decorators (lines ~43-73)

```python
@server.call_tool()
async def read_file(arguments: dict[str, Any]) -> list[TextContent]:
    """Read the contents of a file"""
    # Implementation...
```

Python uses decorators (`@server.call_tool()`) instead of explicit registration.

### 4. Path Security (lines ~19-25)

```python
def validate_path(file_path: str) -> Path:
    """Prevent path traversal attacks"""
    full_path = (WORKSPACE_DIR / file_path).resolve()
    if not str(full_path).startswith(str(WORKSPACE_DIR.resolve())):
        raise ValueError("Access denied")
    return full_path
```

### 5. Server Startup (lines ~132-146)

```python
async with stdio_server() as (read_stream, write_stream):
    await server.run(read_stream, write_stream, ...)
```

Uses Python's async context manager for clean resource handling.

## What You're Learning

This project teaches you:

- ✅ **MCP Server basics** - Creating servers in Python
- ✅ **Tool decorators** - Using `@server.call_tool()`
- ✅ **Async/await** - Python async programming
- ✅ **Input validation** - Using Pydantic models
- ✅ **Error handling** - Try/except patterns
- ✅ **Path operations** - Using pathlib
- ✅ **Security** - Path validation and sandboxing

## Development Tips

### Virtual Environment

Always activate your virtual environment before working:

```bash
# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate
```

### Adding New Tools

Add a new tool by defining an input model and a decorated function:

```python
class DeleteFileInput(BaseModel):
    path: str = Field(description="File to delete")

@server.call_tool()
async def delete_file(arguments: dict[str, Any]) -> list[TextContent]:
    """Delete a file from the workspace"""
    try:
        input_data = DeleteFileInput(**arguments)
        full_path = validate_path(input_data.path)
        full_path.unlink()
        return [TextContent(type="text", text=f"Deleted {input_data.path}")]
    except Exception as e:
        return [TextContent(type="text", text=f"Error: {str(e)}")]
```

### Logging

Use `print(..., file=sys.stderr)` for logging:

```python
print("Debug info", file=sys.stderr)  # Good
print("Debug info")  # Bad - interferes with stdio
```

## Exercises to Try

1. **Add a `file_info` tool**
   - Return file size, modification time, and type
   - Hint: Use `full_path.stat()`

2. **Add a `search_files` tool**
   - Search for text within files
   - Return matching files and line numbers

3. **Improve error handling**
   - Return specific error messages for different error types
   - FileNotFoundError, PermissionError, etc.

## Python vs TypeScript Version

If you're comparing this to the TypeScript version:

| Feature | Python | TypeScript |
|---------|--------|-----------|
| Input validation | Pydantic | Zod |
| Tool registration | Decorators (`@server.call_tool()`) | Method calls (`server.registerTool()`) |
| Async | `async/await` | `async/await` |
| Path handling | `pathlib.Path` | `path` module |
| Type hints | Native Python | TypeScript types |

Both versions do the same thing - choose the language you're more comfortable with!

## Common Python-Specific Issues

1. **Wrong Python version**
   ```bash
   # Check version
   python --version  # Should be 3.10+
   ```

2. **Virtual environment not activated**
   ```bash
   # You should see (venv) in your prompt
   # If not, activate it
   venv\Scripts\activate  # Windows
   ```

3. **Module not found**
   ```bash
   # Make sure you installed dependencies
   pip install -r requirements.txt
   ```

4. **Path separators on Windows**
   ```python
   # Use pathlib - it handles Windows/Unix automatically
   Path("folder") / "file.txt"  # Works everywhere
   ```

## Next Steps

After mastering this project:

1. **Add more tools** (delete, rename, search)
2. **Add resources** (learn resource templates in Python)
3. **Move to Project #2** (Note-Taking Server with persistence)
4. **Try the TypeScript version** to compare languages

## Resources

- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP Documentation](https://modelcontextprotocol.io)
- [Pydantic Documentation](https://docs.pydantic.dev/)
- [Python Pathlib](https://docs.python.org/3/library/pathlib.html)
- [Python Asyncio](https://docs.python.org/3/library/asyncio.html)

## Troubleshooting

**ImportError?** Make sure virtual environment is activated and dependencies are installed

**Server not responding?** Check that you're using stdio transport correctly

**Path errors?** Remember all paths are relative to WORKSPACE_DIR

**Need help?** Check the [MCP Discord](https://discord.gg/mcp) or [GitHub Issues](https://github.com/modelcontextprotocol/python-sdk/issues)