MCP Filesystem Server

: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.

Related MCP server: MCP Filesystem Server

:computer: Technologies

:wrench: Tools

:package: Installation

:heavy_check_mark: Prerequisites

The following software must be installed:

Node.js (>=18.0.0)
Git
pnpm (>=8.0.0)
Docker (optional)
Docker Compose (optional)

: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" ] } } }

Available Tools

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)

Using curl_request Tool (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

Gabriel Maia

License

MIT License

MCP Filesystem Server

:bookmark: About

:computer: Technologies

:wrench: Tools

:package: Installation

:heavy_check_mark: Prerequisites

:arrow_down: Cloning the repository

:arrow_forward: Running the application

Local Development

Using NPM Package

Using Docker

Using Docker Compose

:gear: Usage

Using with Claude Desktop

Using Local Installation (Recommended)

Using NPX

Using Docker

Available Tools

File System Operations

System & Network Operations

Using curl_request Tool (Coming in v1.2.0)

:sparkles: Features

Core Features

New Features in v0.3.0

Configuration Options

:writing_hand: Author

License

Resources

Tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API