Content
# Filesystem MCP Server
A secure, single-binary MCP server for filesystem operations. No runtime dependencies — download, configure allowed directories, and connect to any MCP client.
Tested extensively with Claude Desktop and Claude Code across real-world coding workflows including file editing, codebase search, refactoring, and multi-file batch operations.
## Why this server?
- **Single binary** — no Node.js, Python, or other runtime needed. Download and run
- **Tested with real AI workflows** — battle-tested with Claude Desktop and Claude Code for day-to-day coding tasks
- **18 tools** — goes beyond basic read/write with regex search, pattern-based replacement, auto-indented code insertion, and batch operations
- **Dry-run preview** — preview changes before applying them for replacement and insertion tools
- **Secure by default** — sandboxed to configured directories with symlink attack prevention and path traversal protection
- **Detailed error messages** — when access is denied, errors explain why and suggest fixes
## Installation
### Download a release binary
Download the latest binary for your platform from the [Releases](../../releases) page:
| Platform | Binary |
|----------|--------|
| macOS (Apple Silicon) | `filesystem-mcp-darwin-arm64` |
| macOS (Intel) | `filesystem-mcp-darwin-amd64` |
| Linux (x86_64) | `filesystem-mcp-linux-amd64` |
| Linux (ARM64) | `filesystem-mcp-linux-arm64` |
| Windows | `filesystem-mcp-windows-amd64.exe` |
Make it executable (macOS/Linux):
```bash
chmod +x filesystem-mcp-darwin-arm64
```
### Build from source
```bash
go build -ldflags="-s -w" -o bin/filesystem-mcp ./cmd
```
## Configuration
Set allowed directories using the environment variable:
```bash
export MCP_ALLOWED_DIRS="/path1,/path2,/path with spaces/dir3"
```
## Tools
### Reading
- **`read_file`** — Read a single file, with optional `start_line`/`end_line` for partial reads
- **`read_multiple_files`** — Read multiple files simultaneously in one call
- **`search_in_files`** — Recursive regex search across files. Returns file paths, line numbers, and matched text. Skips binary files automatically. Params: `path`, `pattern`, `file_extensions`, `max_results`, `case_sensitive`
### Writing
- **`write_file`** — Create or overwrite a file. Auto-creates parent directories
- **`append_to_file`** — Add content to end of file. Creates file if it doesn't exist
- **`prepend_to_file`** — Add content to beginning of file. Creates file if it doesn't exist
### Text Replacement
All replacement tools support `dry_run` to preview changes without applying them.
- **`replace_in_file`** — Replace exact string occurrences in a file. Params: `path`, `search`, `replace`, `occurrence` (0=all), `dry_run`
- **`replace_in_file_regex`** — Replace regex pattern matches with capture group support (`$1`, `$2`). Params: `path`, `pattern`, `replace`, `occurrence`, `case_sensitive`, `dry_run`
- **`replace_in_files`** — Batch replace a string across multiple files. Validates all paths before applying. Params: `paths`, `search`, `replace`, `dry_run`
### Regex-Based Insertion
All insertion tools support `dry_run` and `autoIndent` (match surrounding indentation).
- **`insert_after_regex`** — Insert content after a regex pattern match. Params: `path`, `pattern`, `content`, `occurrence` (0=all, default 1), `autoIndent`, `dry_run`
- **`insert_before_regex`** — Insert content before a regex pattern match. Same params as above
### Line Copying
- **`copy_lines`** — Copy a line range from source to destination file directly on disk (no context overhead). Params: `source_path`, `destination_path`, `start_line`, `end_line`, `append`
### Directory Operations
- **`list_directory`** — List directory contents with filtering by pattern, file type, recursion depth, hidden files, and metadata. Params: `path`, `pattern`, `file_type`, `recursive`, `max_depth`, `max_results`, `include_hidden`, `include_metadata`
- **`create_directory`** — Create directory and parents (idempotent)
- **`list_allowed_directories`** — Show accessible directories
### File Management
- **`move_file`** — Move or rename files and directories
- **`get_file_info`** — Get file metadata (size, permissions, modification time)
## Usage with Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"filesystem": {
"command": "/path/to/filesystem-mcp-darwin-arm64",
"env": {
"MCP_ALLOWED_DIRS": "/path1,/path2,/path with spaces/dir3"
}
}
}
}
```
## Security
The server implements defense-in-depth security to prevent unauthorized file access.
### Path Validation
- **Symbolic link resolution**: All paths resolved to canonical form via `filepath.EvalSymlinks()` before validation
- **Path traversal prevention**: Blocks `../` escape attempts
- **Prefix matching protection**: Validates with path separators to prevent `/allowed` matching `/allowed_attacker`
### Symbolic Link Handling
- Symlinks within allowed directories are permitted if their target is also within allowed directories
- Symlinks pointing outside allowed directories are blocked
- Broken symlinks are rejected
- Allowed directories themselves may be symbolic links (resolved during initialization)
### Write Operation Security
- Parent directory chain is validated for new file creation
- Path resolution and validation occur atomically
### Security Logging
- All blocked access attempts are logged with `SECURITY:` prefix
- Logs include both the requested path and its canonical resolution
### Best Practices
- Configure `MCP_ALLOWED_DIRS` with the minimum necessary directories
- Use absolute paths for allowed directories
- Monitor logs for `SECURITY:` messages
## License
MIT License
Connection Info
You Might Also Like
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
Python tool for converting files and office documents to Markdown.
awesome-claude-skills
A curated list of awesome Claude Skills, resources, and tools for...
antigravity-awesome-skills
The Ultimate Collection of 130+ Agentic Skills for Claude...
context-mode
MCP is the protocol for tool access. We're the virtualization layer for context.
claude-context-mode
claude-context-mode plugin reduces MCP context bloat, saving up to 99% of tokens.