phildougherty/mcp-filesystem-remote
If you are the rightful owner of mcp-filesystem-remote 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.
The MCP Filesystem Remote Server is a secure, remote-accessible server that extends the standard MCP filesystem server with additional transport options and Docker support.
MCP Filesystem Remote Server
A secure, remote-accessible Model Context Protocol (MCP) filesystem server with multiple transport options. This server extends the standard MCP filesystem server with HTTP/SSE transport capabilities and Docker support, enabling remote filesystem access while maintaining strict security controls.
Features
Core Filesystem Operations
- File Reading: Complete file contents, head/tail operations for large files
- File Writing: Create new files or overwrite existing ones
- File Editing: Line-based editing with git-style diff preview
- Directory Operations: Create, list (with sizes), recursive tree view
- File Management: Move/rename files and directories
- Search: Recursive file search with pattern matching and exclusion filters
- Metadata: Detailed file information (size, timestamps, permissions)
Security Features
- Path Validation: Strict directory restrictions with allowed-directory enforcement
- Symlink Protection: Validates symlink targets are within allowed directories
- Access Control: Prevents directory traversal attacks
- Input Validation: Comprehensive parameter validation using Zod schemas
Transport Options
- stdio: Traditional MCP stdio transport
- HTTP: Direct HTTP transport for request/response operations
- SSE: Server-Sent Events for persistent connections
Performance Optimizations
- Memory Efficient: Streaming operations for large files
- Chunk Processing: Smart file processing for head/tail operations
- Concurrent Operations: Parallel file operations where safe
Docker Support
- Multi-stage Build: Optimized Docker image with minimal runtime footprint
- Container-ready: Proper argument parsing and port exposure
- Production Ready: Health checks and graceful shutdown handling
Installation
From Source
git clone <repository-url>
cd mcp-filesystem-remote
npm install
npm run build
Using Docker
docker build -t mcp-filesystem-remote .
Usage
Standalone (stdio transport)
node dist/index.js /allowed/directory1 /allowed/directory2
HTTP Transport
node dist/index.js --transport http --port 3000 --host localhost /allowed/directory
SSE Transport
node dist/index.js --transport sse --port 3000 --host 0.0.0.0 /allowed/directory
Docker Usage
# HTTP transport
docker run -p 3000:3000 -v /host/path:/container/path mcp-filesystem-remote \
--transport http --port 3000 --host 0.0.0.0 /container/path
# SSE transport
docker run -p 3000:3000 -v /host/path:/container/path mcp-filesystem-remote \
--transport sse --port 3000 --host 0.0.0.0 /container/path
Configuration
Command Line Options
--transport <mode>
: Transport type (stdio
,http
,sse
) - default:stdio
--port <number>
: Port number for HTTP/SSE transports - default:3000
--host <address>
: Host address to bind to - default:localhost
<directories...>
: One or more allowed directory paths (required)
Environment Variables
NODE_ENV
: Set toproduction
for production deployment (automatically set in Docker)
Security Configuration
The server only allows access to explicitly specified directories. All paths are validated against these allowed directories, including symlink targets.
API Reference
Available Tools
File Operations
-
read_file
: Read complete file contentspath
: File path to readhead
(optional): Read only first N linestail
(optional): Read only last N lines
-
read_multiple_files
: Read multiple files simultaneouslypaths
: Array of file paths
-
write_file
: Write content to filepath
: File pathcontent
: File content
-
edit_file
: Edit file with line-based operationspath
: File pathedits
: Array of {oldText, newText} operationsdryRun
: Preview changes without applying
Directory Operations
-
create_directory
: Create directory (recursive)path
: Directory path
-
list_directory
: List directory contentspath
: Directory path
-
list_directory_with_sizes
: List with file sizespath
: Directory pathsortBy
: Sort by 'name' or 'size'
-
directory_tree
: Recursive directory tree as JSONpath
: Directory path
File Management
-
move_file
: Move/rename files or directoriessource
: Source pathdestination
: Destination path
-
search_files
: Search for files recursivelypath
: Search root pathpattern
: Search pattern (case-insensitive)excludePatterns
: Array of exclusion patterns
Information
-
get_file_info
: Get file metadatapath
: File path
-
list_allowed_directories
: List allowed directories
HTTP Endpoints (HTTP/SSE modes)
GET /health
: Health check endpointPOST /
: MCP protocol endpoint (HTTP mode)GET /message
: SSE connection endpoint (SSE mode)POST /message
: MCP protocol endpoint (SSE mode)
Security Considerations
Directory Restrictions
- Only explicitly allowed directories are accessible
- Symlinks are validated to ensure targets are within allowed directories
- Path traversal attempts are blocked
Input Validation
- All inputs are validated using Zod schemas
- File paths are normalized and resolved
- Invalid operations return descriptive error messages
Network Security
- CORS is enabled for web client access
- Health check endpoint provides minimal information
- Graceful shutdown prevents data loss
Examples
Basic File Operations
// Read a configuration file
{
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": {"path": "/allowed/config/app.json"}
}
}
// Edit a file with diff preview
{
"method": "tools/call",
"params": {
"name": "edit_file",
"arguments": {
"path": "/allowed/src/main.js",
"edits": [{"oldText": "const port = 3000", "newText": "const port = 8080"}],
"dryRun": true
}
}
}
Directory Management
// Get directory tree structure
{
"method": "tools/call",
"params": {
"name": "directory_tree",
"arguments": {"path": "/allowed/project"}
}
}
// Search for specific files
{
"method": "tools/call",
"params": {
"name": "search_files",
"arguments": {
"path": "/allowed/src",
"pattern": ".js",
"excludePatterns": ["node_modules/**", "dist/**"]
}
}
}
Development
Building
npm run build # Compile TypeScript
npm run watch # Watch mode for development
Docker Development
docker build -t mcp-filesystem-remote:dev .
docker run -p 3000:3000 -v $(pwd):/app/src mcp-filesystem-remote:dev
Testing
The server includes comprehensive error handling and logging. Debug output is sent to stderr to avoid interfering with MCP protocol communication.
License
MIT License - see package.json for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Support
- Health Check: Access
/health
endpoint for server status - Logging: Check stderr for detailed debug information
- Error Handling: All operations include descriptive error messages
This server provides a secure, efficient way to access filesystem operations remotely while maintaining the standard MCP protocol interface. Perfect for containerized environments, web applications, or any scenario requiring remote filesystem access with strict security controls.