# 📂 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.