home / mcp / secure mcp filesystem server

Secure MCP Filesystem Server

Provides secure filesystem access for AI models within predefined directories using MCP

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "a-niranjan-mcp-filesystem": {
      "command": "npx",
      "args": [
        "@gabrielmaialva33/mcp-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Secure MCP Filesystem Server enables AI models to access filesystem data securely by exposing predefined directories through the Model Context Protocol. It enforces strict path validation and provides flexible deployment options, so you can run it locally, via npm/npx, or in Docker, while keeping access tightly controlled.

How to use

You interact with the MCP Filesystem Server through an MCP client by starting the server in one of several supported ways. Each method lets you point the server at the directories you want to expose and then connect your MCP-enabled client to operate on those files.

How to install

Prerequisites you need to have before installing and running the server are Node.js (version 18 or higher), Git, pnpm (version 8 or higher), and Docker (optional for containerized runs). Install the necessary software on your system before proceeding.

# Clone the repository
$ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
$ cd mcp-filesystem

# Install dependencies
$ pnpm install

# Build the application
$ pnpm build

# Start the server for a specific allowed directory (local development)
$ pnpm start /path/to/allowed/directory

# Or start with a configuration file
$ pnpm start --config=config.json

# Alternatively, install the package globally and run
$ npm install -g @gabrielmaialva33/mcp-filesystem
$ mcp-filesystem /path/to/allowed/directory

# Or use npx without installation
$ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory
$ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

# Docker usage (build image first)
$ docker build -t gabrielmaialva33/mcp-filesystem .
$ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

# Docker usage with a 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

# Docker Compose can be used for orchestrating the service
$ mkdir -p data
$ docker-compose up -d

Additional configuration and example usage

You can configure the server with a JSON configuration file to control access, logging, caching, metrics, and security settings. An example configuration is shown below to illustrate the available fields and their typical values.

Configuration example

{
  "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
  }
}

Available tools

read_file

Read a file's content from an allowed directory with path validation to ensure access remains within predefined boundaries.

read_multiple_files

Read multiple files in a single operation while enforcing access restrictions.

write_file

Create or overwrite a file within an allowed directory, subject to size and path validations.

edit_file

Edit a file with diff preview to show changes before applying them.

create_directory

Create directories recursively inside allowed paths.

list_directory

List the contents of a directory that the server has permission to access.

directory_tree

Get a recursive tree view of an allowed directory.

move_file

Move or rename files within allowed directories.

search_files

Find files matching patterns across allowed directories.

get_file_info

Retrieve metadata for files and directories.

list_allowed_directories

Display all directories that are accessible by the server.

get_metrics

View server performance metrics such as operation counts, errors, and timings.

execute_command

Securely execute system commands with strict validation rules.

curl_request

Make HTTP requests to external APIs from within the server (upcoming feature).