Filesystem MCP Server
Node.js server implementing Model Context Protocol (MCP) for filesystem operations with comprehensive permission controls and enhanced functionality.
Features
- Granular permission controls (read-only, full access, or specific operation permissions)
- Secure file operations within allowed directories
- File operations:
- Read/write/modify files
- Create/list/delete directories
- Move files/directories
- Search files by name or extension
- Get file metadata
- Directory operations:
- Tree view of directory structures
- Recursive operations with exclusion patterns
- Utility functions:
- XML to JSON conversion
- Multiple file operations in one call
- Advanced file editing with pattern matching
- Security features:
- Symlink control
- Path validation
- Sandboxed operations
Note: The server will only allow operations within directories specified via args
and according to the configured permissions.
API
Resources
file://system
: File system operations interface
Tools
- read_file
- Read complete contents of a file
- Input:
path
(string) - Reads complete file contents with UTF-8 encoding
- read_multiple_files
- Read multiple files simultaneously
- Input:
paths
(string[]) - Failed reads won't stop the entire operation
- create_file
- Create a new file with content
- Inputs:
path
(string): File locationcontent
(string): File content
- Fails if file already exists
- Requires
create
permission
- modify_file
- Modify an existing file with new content
- Inputs:
path
(string): File locationcontent
(string): New file content
- Fails if file doesn't exist
- Requires
edit
permission
- edit_file
- Make selective edits using pattern matching and formatting
- Features:
- Line-based and multi-line content matching
- Whitespace normalization with indentation preservation
- Multiple simultaneous edits with correct positioning
- Indentation style detection and preservation
- Git-style diff output with context
- Preview changes with dry run mode
- Inputs:
path
(string): File to editedits
(array): List of edit operationsoldText
(string): Text to search for (exact match)newText
(string): Text to replace with
dryRun
(boolean): Preview changes without applying (default: false)
- Returns detailed diff for dry runs, otherwise applies changes
- Requires
edit
permission - Best Practice: Always use dryRun first to preview changes
- create_directory
- Create new directory or ensure it exists
- Input:
path
(string) - Creates parent directories if needed
- Succeeds silently if directory exists
- Requires
create
permission
- list_directory
- List directory contents with [FILE] or [DIR] prefixes
- Input:
path
(string) - Returns detailed listing of files and directories
- directory_tree
- Get recursive tree view of directory structure
- Input:
path
(string) - Returns JSON structure with files and directories
- Each entry includes name, type, and children (for directories)
- move_file
- Move or rename files and directories
- Inputs:
source
(string): Source pathdestination
(string): Destination path
- Fails if destination exists
- Works for both files and directories
- Requires
move
permission
- delete_file
- Delete a file
- Input:
path
(string) - Fails if file doesn't exist
- Requires
delete
permission
- delete_directory
- Delete a directory
- Inputs:
path
(string): Directory to deleterecursive
(boolean): Whether to delete contents (default: false)
- Fails if directory is not empty and recursive is false
- Requires
delete
permission
- search_files
- Recursively search for files/directories
- Inputs:
path
(string): Starting directorypattern
(string): Search patternexcludePatterns
(string[]): Exclude patterns (glob format supported)
- Case-insensitive matching
- Returns full paths to matches
- find_files_by_extension
- Find all files with specific extension
- Inputs:
path
(string): Starting directoryextension
(string): File extension to findexcludePatterns
(string[]): Optional exclude patterns
- Case-insensitive extension matching
- Returns full paths to matching files
- get_file_info
- Get detailed file/directory metadata
- Input:
path
(string) - Returns:
- Size
- Creation time
- Modified time
- Access time
- Type (file/directory)
- Permissions
- get_permissions
- Get current server permissions
- No input required
- Returns:
- Permission flags (readonly, fullAccess, create, edit, move, delete)
- Symlink following status
- Number of allowed directories
- list_allowed_directories
- List all directories the server is allowed to access
- No input required
- Returns array of allowed directory paths
- xml_to_json
- Convert XML file to JSON format
- Inputs:
xmlPath
(string): Source XML filejsonPath
(string): Destination JSON fileoptions
(object): Optional settingsignoreAttributes
(boolean): Skip XML attributes (default: false)preserveOrder
(boolean): Maintain property order (default: true)format
(boolean): Pretty print JSON (default: true)indentSize
(number): JSON indentation (default: 2)
- Requires
read
permission for XML file - Requires
create
oredit
permission for JSON file
- xml_to_json_string
- Convert XML file to JSON string
- Inputs:
xmlPath
(string): Source XML fileoptions
(object): Optional settingsignoreAttributes
(boolean): Skip XML attributes (default: false)preserveOrder
(boolean): Maintain property order (default: true)
- Requires
read
permission for XML file - Returns JSON string representation
- xml_query
- Query XML file using XPath expressions
- Inputs:
path
(string): Path to the XML filequery
(string, optional): XPath query to executestructureOnly
(boolean, optional): Return only tag structuremaxBytes
(number, optional): Maximum bytes to read (default: 1MB)includeAttributes
(boolean, optional): Include attribute info (default: true)
- XPath examples:
- Get all elements:
//tagname
- Get elements with specific attribute:
//tagname[@attr="value"]
- Get text content:
//tagname/text()
- Get all elements:
- Memory efficient for large XML files
- Returns JSON representation of query results or structure
- xml_structure
- Analyze XML structure without reading entire file
- Inputs:
path
(string): Path to the XML filedepth
(number, optional): How deep to analyze (default: 2)includeAttributes
(boolean, optional): Include attribute analysismaxBytes
(number, optional): Maximum bytes to read (default: 1MB)
- Returns statistical information about elements, attributes, and structure
- Useful for understanding large XML files before detailed analysis
Permissions & Security
The server implements a comprehensive security model with granular permission controls:
Directory Access Control
- Operations are strictly limited to directories specified during startup via
args
- All operations (including symlink targets) must remain within allowed directories
- Path validation ensures no directory traversal or access outside allowed paths
Permission Flags
- --readonly: Enforces read-only mode, overriding all other permission flags
- --full-access: Enables all operations (create, edit, move, delete)
- Individual permission flags (require explicit enabling unless --full-access is set):
- --allow-create: Allow creation of new files and directories
- --allow-edit: Allow modification of existing files
- --allow-move: Allow moving/renaming files and directories
- --allow-delete: Allow deletion of files and directories
Default Behavior: If no permission flags are specified, the server runs in read-only mode. To enable any write operations, you must use either --full-access
or specific --allow-*
flags.
Symlink Handling
- By default, symlinks are followed (both link and target must be in allowed directories)
- --no-follow-symlinks: Disable symlink following (operations act on the link itself)
Usage with Claude Desktop and Cursor
Add appropriate configuration to either claude_desktop_config.json
(for Claude Desktop) or .cursor/mcp.json
(for Cursor):
Cursor Configuration
In .cursor/mcp.json
:
Docker Configuration
For Claude Desktop with Docker:
NPX Configuration
For either Claude Desktop or Cursor with NPX:
Permission Flag Examples
You can configure the server with various permission combinations:
Note: --readonly
takes precedence over all other permission flags, and --full-access
enables all operations unless --readonly
is specified.
Multiple Directories and Permissions
When specifying multiple directories, permission flags apply globally to all directories:
If you need different permission levels for different directories, create multiple server configurations:
Command Line Examples
- Read-only access:
- Full access:
- Specific permissions:
- No symlink following:
Build
Docker build:
License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
This server cannot be installed
Node.js server implementing Model Context Protocol (MCP) for filesystem operations with comprehensive permission controls, allowing secure file and directory manipulation with granular access restrictions.
Related MCP Servers
- -securityAlicense-qualityNode.js server implementing Model Context Protocol (MCP) for filesystem operations.Last updated -29,12443,205JavaScriptMIT License
- -securityFlicense-qualityNode.js server implementing Model Context Protocol for filesystem operations, allowing Claude to read, write, and manipulate files and directories in specified locations.Last updated -29,124JavaScript
- -securityAlicense-qualityA 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 -471JavaScriptMIT License
- -securityFlicense-qualityA Node.js server that implements Model Context Protocol (MCP) for controlling HWP (Korean word processor) documents, allowing AI assistants like Claude to create and manipulate Hangul documents.Last updated -27Python