📂 filesystem-mcp

<p align="center"> <a href="https://pypi.org/project/filesystem-mcp/"> <img src="https://img.shields.io/pypi/v/filesystem-mcp" alt="PyPI"> </a> <a href="https://python.org/downloads/"> <img src="https://img.shields.io/pypi/pyversions/filesystem-mcp" alt="Python"> </a> <a href="https://opensource.org/licenses/MIT"> <img src="https://img.shields.io/pypi/l/filesystem-mcp" alt="License"> </a> </p>

Model Context Protocol (MCP) server for file system operations. Enable AI assistants like Claude, Cursor, and others to read, write, and manage files on your local system.

🚀 Features

• 📖 Read files - Read file contents with size limits
• 📂 List directories - View files with metadata (size, type)
• ✏️ Write files - Create and update files
• 🗑️ Delete files - Remove files and directories
• 🔍 Search files - Glob pattern matching
• 📊 File info - Get detailed metadata
• 📁 Directory operations - Create, copy, move directories

📦 Installation

pip install filesystem-mcp

🔧 Usage

CLI Mode

# Start the MCP server (read-write mode)
filesystem-mcp --directory /path/to/your/project

# Start in read-only mode
filesystem-mcp --directory /path/to/your/project --readonly

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "filesystem-mcp",
      "args": ["--directory", "/path/to/your/project"]
    }
  }
}

Cursor

Add to Cursor settings (MCP configuration):

{
  "mcpServers": {
    "filesystem": {
      "command": "filesystem-mcp",
      "args": ["--directory", "/path/to/your/project"]
    }
  }
}

🛠️ Available Tools

Tool	Description	Write
read_file	Read contents of a file	❌
list_directory	List files in a directory	❌
write_file	Create or write to a file	✅
delete_file	Delete a file or directory	✅
create_directory	Create a new directory	✅
search_files	Search files by glob pattern	❌
get_file_info	Get file metadata	❌
copy_file	Copy a file or directory	✅
move_file	Move or rename a file	✅

📝 Example

from filesystem_mcp import FileSystemServer

# Create server instance
server = FileSystemServer(root_directory="/path/to/project")

# Run the server
server.run()

🔐 Security

• Path restrictions: All operations are restricted to the specified root directory
• File size limits: Maximum 1MB for file reads
• Optional read-only mode: Use --readonly flag to disable all write operations

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE for details.