Content
# 📂 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
```bash
pip install filesystem-mcp
```
## 🔧 Usage
### CLI Mode
```bash
# 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`:
```json
{
"mcpServers": {
"filesystem": {
"command": "filesystem-mcp",
"args": ["--directory", "/path/to/your/project"]
}
}
}
```
### Cursor
Add to Cursor settings (MCP configuration):
```json
{
"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
```python
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](LICENSE) for details.
