gomcpgo/filesys
3.3
If you are the rightful owner of filesys and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A secure Model Context Protocol (MCP) server that provides filesystem operations with controlled access to specified directories.
Tools
4
Resources
0
Prompts
0
Filesystem MCP Server
A secure Model Context Protocol (MCP) server that provides filesystem operations with controlled access to specified directories.
Features
- Directory access controlled via environment variables
- File operations within allowed directories only
- Thread-safe caching of allowed directories
- Proper handling of paths with spaces
Installation
go get github.com/gomcpgo/filesys
Configuration
Set allowed directories using the environment variable:
export MCP_ALLOWED_DIRS="/path1,/path2,/path with spaces/dir3"
Tools
File Reading
read_file: Read single file contentsread_multiple_files: Read multiple files simultaneously
File Writing
write_file: Create or overwrite files
Directory Operations
create_directory: Create new directorieslist_directory: List directory contentslist_allowed_directories: Show accessible directories
File Management
move_file: Move or rename files and directoriesget_file_info: Get file metadatasearch_files: Search files recursively with pattern matching
Usage with Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"filesystem": {
"command": "/path/to/filesys",
"env": {
"MCP_ALLOWED_DIRS": "/path1,/path2,/path with spaces/dir3"
}
}
}
}
Tool Examples
Reading a File
{
"name": "read_file",
"arguments": {
"path": "/allowed/path/file.txt"
}
}
Listing Directory
{
"name": "list_directory",
"arguments": {
"path": "/allowed/path"
}
}
Security
The filesystem MCP server implements comprehensive security measures to prevent unauthorized file access:
Path Validation
- Symbolic link resolution: All paths are resolved to their canonical form using
filepath.EvalSymlinks()before validation - Canonical path checking: Paths are validated against allowed directories only after resolving all symbolic links
- Path traversal prevention: Attempts to escape allowed directories using
../or similar techniques are blocked - Prefix matching protection: Directory prefixes are validated with path separators to prevent
/allowedfrom matching/allowed_attacker
Symbolic Link Handling
- Legitimate symlinks: Symbolic links within allowed directories are permitted (if their target is also within allowed directories)
- Attack prevention: Symbolic links pointing outside allowed directories are automatically blocked
- Broken symlinks: Broken symbolic links (pointing to non-existent targets) are rejected for security
- Allowed directory symlinks: Allowed directories themselves may be symbolic links (resolved during initialization)
Write Operation Security
- Non-existent paths: When creating new files or directories, the parent directory chain is validated
- Parent validation: Only paths whose parent directories are within allowed areas can be created
- Atomic validation: Path resolution and validation occur atomically to prevent race conditions
Attack Prevention
The server protects against:
- Symlink-based directory traversal attacks
- Path traversal with
../sequences - Broken symlink exploitation
- Prefix matching attacks (
/allowedvs/allowed_attacker) - Nested symlink chains escaping allowed directories
Security Logging
- All blocked access attempts are logged with "SECURITY:" prefix
- Logs include both the requested path and its canonical resolution
- Helps detect and investigate potential attack attempts
Best Practices
- Configure
MCP_ALLOWED_DIRSwith the minimum necessary directories - Use absolute paths for allowed directories
- Monitor logs for "SECURITY:" messages indicating blocked access attempts
- Regularly review allowed directory configurations
Building
go build -o bin/filesys cmd/main.go
License
MIT License
Contributing
Pull requests welcome. Please ensure:
- Tests pass
- New features include documentation
- Code follows project style
