andrewlidong/filesystem-explorer-mcp

File System Explorer MCP Server

A Model Context Protocol (MCP) server that provides safe file system operations for AI assistants, perfect for use with Claude Code.

Features

• Safe file browsing: Restricted to a root directory for security
• File reading: Read text files with automatic language detection
• Metadata analysis: Get detailed file and directory information
• File search: Find files by pattern or extension
• Project analysis: Analyze project structure and languages used
• Security controls: File size limits, extension filtering, directory restrictions

Installation

npm install

Usage

# Start the server with default configuration
npm start

# Start the server with custom configuration
ROOT_DIR=/path/to/directory PORT=4000 npm start

Environment Variables

• PORT: The port to run the server on (default: 3000)
• ROOT_DIR: The root directory to serve files from (default: current working directory)

API Methods

listDirectory

Lists files and directories in the specified path.

{
  "path": "src"
}

readFile

Reads the content of a file with language detection.

{
  "path": "src/index.ts"
}

getMetadata

Gets metadata for a file or directory.

{
  "path": "package.json"
}

searchFiles

Searches for files matching a pattern.

{
  "pattern": "\\.ts$",
  "directory": "src"
}

getProjectInfo

Gets overview information about the project structure.

{}

exists

Checks if a file or directory exists.

{
  "path": "src/index.ts"
}

Security Considerations

• All paths are normalized and checked to prevent directory traversal attacks
• Maximum file size is limited to 10MB by default
• Only allowed file extensions can be read
• All operations are restricted to the specified root directory

License

ISC