:bookmark: About
MCP Filesystem Server provides secure filesystem access for AI models through the Model Context Protocol. It
enforces strict path validation and only allows access to predefined directories.
:computer: Technologies
:package: Installation
:heavy_check_mark: Prerequisites
The following software must be installed:
:arrow_down: Cloning the repository
$ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
$ cd mcp-filesystem
:arrow_forward: Running the application
Local Development
# Install dependencies
$ pnpm install
# Build the application
$ pnpm build
# Run the server (specify directory to allow access to)
$ pnpm start /path/to/allowed/directory
# Or use configuration file
$ pnpm start --config=config.json
Using NPM Package
# Install globally
$ npm install -g @gabrielmaialva33/mcp-filesystem
# Run the server
$ mcp-filesystem /path/to/allowed/directory
# Or use with npx (no installation needed)
$ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory
# Create a sample configuration file
$ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json
Using Docker
# Build the Docker image
$ docker build -t gabrielmaialva33/mcp-filesystem .
# Run using Docker
$ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data
# Use with config file
$ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json
Using Docker Compose
# Create a data directory
$ mkdir -p data
# Start the server
$ docker-compose up -d
:gear: Usage
Using with Claude Desktop
Claude Desktop can be configured to use this MCP server for filesystem access. Add the following to your
claude_desktop_config.json:
Using Local Installation (Recommended)
{
"mcpServers": {
"filesystem": {
"command": "mcp-filesystem",
"args": [
"/Users/gabrielmaia/Documents",
"/Users/gabrielmaia/Desktop",
"/Users/gabrielmaia/Downloads"
]
}
}
}
Make sure to make the executable available globally:
# Make the binary executable
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem
Using NPX
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@gabrielmaialva33/mcp-filesystem",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}
Using Docker
Note: When using Docker, all directories must be mounted to /projects by default. Adding the ro flag will make the
directory read-only.
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
"--mount",
"type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
"--mount",
"type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
"gabrielmaialva33/mcp-filesystem",
"/projects"
]
}
}
}
The MCP Filesystem Server provides these tools:
File System Operations
- read_file: Read a file's content
- read_multiple_files: Read multiple files at once
- write_file: Create or overwrite a file
- edit_file: Make precise edits with diff preview
- create_directory: Create directories recursively
- list_directory: List directory contents
- directory_tree: Get a recursive tree view
- move_file: Move or rename files
- search_files: Find files matching patterns
- get_file_info: Get file metadata
- list_allowed_directories: See accessible directories
System & Network Operations
- get_metrics: View server performance metrics (v0.3.0+)
- execute_command: Execute system commands securely (v0.3.1+)
- curl_request: Execute HTTP requests to external APIs (coming in v1.2.0)
The curl_request tool will allow you to make HTTP requests to external APIs:
// Example: Making a GET request with authentication
curl_request({
url: 'https://api.example.com/data',
method: 'GET',
headers: {
Authorization: 'Bearer your_token_here',
},
})
// Example: POST request with JSON data
curl_request({
url: 'https://api.example.com/create',
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
data: '{"name":"Example","value":123}',
})
See the docs/curl-tool-examples.md file for more detailed examples.
:sparkles: Features
Core Features
- Secure Access: Strict path validation prevents unauthorized access
- File Operations: Read, write, edit, and move files
- Directory Operations: Create, list, get tree views, and search directories
- Metadata Access: View file and directory information
- Command Execution: Securely execute system commands with strict validation
- Docker Support: Easy deployment with Docker and Docker Compose
New Features in v0.3.0
- Structured Logging: Detailed logging with different levels (debug, info, warn, error)
- Performance Metrics: Track operation counts, errors, and execution times
- Configuration Management: Support for JSON configuration files
- Path Caching: Improved performance for frequently accessed paths
- Improved Error Handling: Specialized error types with structured information
- File Size Validation: Prevent loading excessively large files
- CLI Improvements: Help command, version info, and config generation
Configuration Options
You can create a configuration file using:
$ mcp-filesystem --create-config=config.json
Example configuration:
{
"allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
"logLevel": "info",
"logFile": "/path/to/logs/mcp-filesystem.log",
"serverName": "secure-filesystem-server",
"serverVersion": "0.3.0",
"cache": {
"enabled": true,
"maxSize": 1000,
"ttlMs": 60000
},
"metrics": {
"enabled": true,
"reportIntervalMs": 60000
},
"security": {
"maxFileSize": 10485760,
"allowSymlinks": true,
"validateRealPath": true
}
}
:writing_hand: Author
License
MIT License