A secure Model Context Protocol (MCP) server providing filesystem access within predefined directories
About |
Technologies |
Tools |
Installation |
Usage |
License
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.
Technologies
Installation
Prerequisites
The following software must be installed:
Cloning the repository
$ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
$ cd mcp-filesystem
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
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.
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
}
}
Author
License
MIT License
© 2024-present Maia
Tools