A production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude to perform sophisticated file system operations safely and efficiently.
| Category | Capabilities |
|---|---|
| 📄 File Operations | Read, write, append, copy, move, delete files with encoding support |
| 📁 Directory Operations | List, create, delete, copy directories with recursive options |
| 🔍 Search & Discovery | Pattern matching, filters by size/date/type, duplicate detection |
| ⚡ Batch Operations | Bulk rename, directory sync, statistics generation |
| 🔒 Security | Path validation, size limits, safe defaults, preview modes |
| 📝 Prompts | Built-in workflows for organizing, cleanup, and backup |
# Using pip
pip install filesystem-mcp
# Using uv (recommended)
uv pip install filesystem-mcp
# From source
git clone https://github.com/yourusername/filesystem-mcp.git
cd filesystem-mcp
pip install -e .Add to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"filesystem": {
"command": "filesystem-mcp",
"env": {
"FILESYSTEM_MCP_ALLOWED_DIRS": "/Users/yourname/Documents:/Users/yourname/Projects"
}
}
}
}Once configured, you can ask Claude things like:
"Organize my Downloads folder by file type"
"Find all Python files modified this week in my projects"
"Show me duplicate files in my Photos folder"
"Sync my project folder to my backup drive"
File Operations
| Tool | Description |
|---|---|
read_file |
Read text file contents with encoding support |
write_file |
Write content to file, create if doesn't exist |
append_file |
Append content to existing file |
delete_file |
Delete a file |
copy_file |
Copy file to new location |
move_file |
Move or rename a file |
Directory Operations
| Tool | Description |
|---|---|
list_directory |
List contents with filtering and recursion |
create_directory |
Create new directory with parent creation |
delete_directory |
Delete directory (with recursive option) |
copy_directory |
Copy directory tree |
Search & Analysis
| Tool | Description |
|---|---|
search_files |
Search with pattern, size, date filters |
get_file_metadata |
Get detailed file info including hashes |
find_duplicates |
Find duplicate files by content hash |
get_directory_stats |
Directory statistics and analysis |
Batch Operations
| Tool | Description |
|---|---|
batch_rename |
Rename multiple files with regex patterns |
sync_directories |
Synchronize directories with preview |
| URI | Description |
|---|---|
filesystem://config |
Server configuration |
filesystem://home |
User's home directory |
filesystem://cwd |
Current working directory |
| Prompt | Description |
|---|---|
organize_files |
Guide for organizing files by extension, date, or size |
cleanup_directory |
Find duplicates, empty dirs, temp files |
backup_directory |
Backup workflow with verification |
| Variable | Description | Default |
|---|---|---|
FILESYSTEM_MCP_ALLOWED_DIRS |
Colon-separated allowed directories | User home |
FILESYSTEM_MCP_MAX_FILE_SIZE |
Maximum file size in MB | 50 |
┌─────────────────────────────────────────────────────────┐
│ MCP Client (Claude) │
└─────────────────────────┬───────────────────────────────┘
│ MCP Protocol
┌─────────────────────────▼───────────────────────────────┐
│ Filesystem MCP Server │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Path Validator │ │
│ │ • Resolves all paths to absolute │ │
│ │ • Validates against allowed directories │ │
│ │ • Prevents path traversal attacks │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Resource Limits │ │
│ │ • Max file size: 50MB (configurable) │ │
│ │ • Max search results: 100 │ │
│ │ • Preview mode for destructive ops │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────┘
│ Validated Operations Only
┌─────────────────────────▼───────────────────────────────┐
│ File System │
│ (Allowed Directories Only) │
└─────────────────────────────────────────────────────────┘
git clone https://github.com/yourusername/filesystem-mcp.git
cd filesystem-mcp
python -m venv .venv
source .venv/bin/activate # or `.venv\Scripts\activate` on Windows
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage
pytest --cov=filesystem_mcp --cov-report=html
# Run specific test file
pytest tests/test_server.py -v# Format code
black src/ tests/
# Lint
ruff check src/ tests/
# Type check
mypy src/# Start the server (stdio mode)
filesystem-mcp
# Or run directly
python -m filesystem_mcp.serverfilesystem-mcp/
├── src/filesystem_mcp/
│ ├── __init__.py # Package exports
│ └── server.py # Main MCP server implementation
├── tests/
│ └── test_server.py # Comprehensive test suite
├── examples/
│ ├── claude_desktop_config.json
│ └── example_client.py # Programmatic usage example
├── docs/
│ ├── API.md # Full API documentation
│ └── SECURITY.md # Security considerations
├── .github/
│ └── workflows/
│ └── tests.yml # CI/CD pipeline
├── pyproject.toml # Package configuration
└── README.md
import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
async def main():
server_params = StdioServerParameters(
command="filesystem-mcp",
env={"FILESYSTEM_MCP_ALLOWED_DIRS": "/tmp"}
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# List directory
result = await session.call_tool(
"list_directory",
arguments={"path": "/tmp", "pattern": "*.txt"}
)
print(result)
asyncio.run(main())User: "Find all files larger than 10MB in my Documents folder"
Claude: I'll search for large files in your Documents folder.
[Calls search_files with min_size=10485760]
Found 7 files larger than 10MB:
1. video_project.mp4 (245 MB) - Modified: 2024-01-15
2. dataset.csv (89 MB) - Modified: 2024-01-10
...
Contributions are welcome! Please read our Contributing Guide first.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Anthropic for creating the Model Context Protocol
- FastMCP for the excellent Python SDK
- The MCP community for inspiration and feedback
Rosalina Torres - MS Data Analytics Engineering, Northeastern University
- 📧 Email: torres.ros@northeastern.edu
- 🔗 LinkedIn: linkedin.com/in/rosalina-torres
- 💻 GitHub: @rosalinatorres888
Made with ❤️ for the AI community