MCP Filesystem Server

: 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

TypeScript
Node.js
MCP SDK
Zod
Docker
pnpm

: Tools

: Installation

: Prerequisites

The following software must be installed:

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

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

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.

: 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


Gabriel Maia

License

MIT License

Deploy Server

HTTP connection URL

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

Provides secure filesystem access for AI models through the Model Context Protocol with strict path validation, file operations, directory management, and system command execution within predefined directories.

Related MCP Servers

MCP File Server
codyde
A
security
F
license
A
quality
Enables AI models to perform file system operations (reading, creating, and listing files) on a local file system through a standardized Model Context Protocol interface.
Last updated -
3
MCP Local File Reader
sworddut
-
security
A
license
-
quality
A Model Context Protocol (MCP) server that allows AI models to safely access and interact with local file systems, enabling reading file contents, listing directories, and retrieving file metadata.
Last updated -
9
9
MIT License
BetterMCPFileServer
MartinSchlott
-
security
A
license
-
quality
A redesigned Model Context Protocol server that enables AI models to access filesystems through privacy-preserving path aliases with an optimized 6-function API interface.
Last updated -
MIT License
MCP Filesystem Server
gabrielmaialva33
A
security
A
license
A
quality
A secure Model Context Protocol server that provides controlled filesystem access within predefined directories, enabling AI models to perform file and directory operations with strict path validation.
Last updated -
16
4
7
MIT License

View all related MCP servers

Appeared in Searches

How to copy files to a directory

MCP Filesystem Server

: About

: Technologies

: Tools

: Installation

: Prerequisites

: Cloning the repository

: Running the application

Local Development

Using NPM Package

Using Docker

Using Docker Compose

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

: Features

Core Features

New Features in v0.3.0

Configuration Options

: Author

License

Tools

Related MCP Servers

MCP File Server

MCP Local File Reader

BetterMCPFileServer

MCP Filesystem Server

Appeared in Searches

New MCP Servers

MCP directory API