MCP Smart Filesystem Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Smart Filesystem Server search for all async functions in the src directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Smart Filesystem Server
An LLM-optimized Model Context Protocol (MCP) filesystem server with intelligent features designed for effective AI agent interaction.
Features
🚀 Intelligent File Pagination
Automatically chunks large files (>500 lines) into manageable pieces
Simple
start_lineparameter for easy navigationClear indicators when more content is available
Prevents context overflow in LLM conversations
⚡ Ripgrep Integration
Lightning-fast code searching across entire codebase
Regex pattern support with helpful examples
File-specific searching (like Ctrl+F with regex)
Flexible filtering by file type, path, and more
🔒 Security Sandboxing
Strict directory access control
Symlink attack prevention
Path traversal protection
Only accesses files within allowed directories
🎯 LLM-Friendly Design
Helpful suggestions in responses
Examples for common search patterns
Reading strategy recommendations for large files
Clear error messages with actionable guidance
Related MCP server: Local Explorer MCP
Tools
1. list_directory
List directory contents with metadata.
{
"path": "src"
}Returns: Files, directories, sizes, line counts, and summary statistics.
2. read_file
Read file contents with automatic pagination for large files.
{
"path": "src/large-file.ts",
"start_line": 0
}For files >500 lines, returns first 500 lines with hasMore: true and nextStartLine.
Read next chunk with start_line: 500, then 1000, etc.
3. search_code
Search for code patterns using ripgrep (very fast).
Examples:
Find any type declaration (class/struct/interface/enum):
{
"pattern": "\\b(class|struct|interface|enum)\\s+ServiceName\\b",
"filePattern": "*.ts"
}Find method with any access modifier:
{
"pattern": "\\b(public|private|protected).*\\s+methodName\\s*\\(",
"path": "src/directory"
}Find all async functions:
{
"pattern": "async\\s+.*\\s*\\(",
"caseInsensitive": true,
"contextLines": 3
}Options:
pattern(required): Regex patternpath: Limit to specific directoryfilePattern: File glob (e.g.,*.js,*.{ts,tsx},!*test*)caseInsensitive: Ignore casecontextLines: Lines of context (default: 2)maxResults: Max results (default: 50)literalString: Treat as literal, not regexwordBoundary: Match whole words only
4. search_in_file
Search within a specific file (like Ctrl+F with regex).
{
"path": "src/server.ts",
"pattern": "app\\.use\\(",
"contextLines": 3
}5. find_files
Find files by name pattern.
{
"pattern": "*Handler*.ts"
}Pattern examples:
config.json- Exact name*.config- Wildcard*Service*- Contains "Service"*.{ts,tsx,js}- Multiple extensions
6. get_file_info
Get file metadata without reading contents.
{
"path": "src/large-file.ts"
}Returns: Size, line count, language, binary status, and reading strategy for large files.
7. list_allowed_directories
Show accessible directories (security boundaries).
{}Installation
Docker (Recommended)
# Build image
docker build -t mcp-filesystem-smart .
# Run with workspace mounted
docker run -i --rm \
-v /path/to/your/project:/workspace:ro \
mcp-filesystem-smartThe :ro flag makes the directory read-only for extra security.
Configuration via Environment Variables
Customize behavior with environment variables:
docker run -i --rm \
-e MCP_LINES_PER_PAGE=1000 \
-e MCP_MAX_SEARCH_RESULTS=200 \
-v /path/to/your/project:/workspace:ro \
mcp-filesystem-smartAvailable Variables:
MCP_LINES_PER_PAGE- Lines per page when reading files (default: 500)MCP_MAX_SEARCH_RESULTS- Search results per page (default: 100)
Local Installation
npm install
npm run build
node dist/index.js /path/to/allowed/directoryUsage with MCP Clients
Configuration Example
{
"mcpServers": {
"filesystem-smart": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/home/user/projects/myapp:/workspace:ro",
"mcp-filesystem-smart"
]
}
}
}Multiple Allowed Directories
# Local
node dist/index.js /path/to/dir1 /path/to/dir2
# Docker (mount multiple volumes)
docker run -i --rm \
-v /path/to/dir1:/workspace1:ro \
-v /path/to/dir2:/workspace2:ro \
mcp-filesystem-smart /workspace1 /workspace2LLM Usage Patterns
Pattern 1: Find Type Declaration (Unknown Kind)
When you don't know if something is a class, struct, interface, or record:
search_code({
pattern: "\\b(class|struct|record|interface|enum)\\s+MyType\\b",
filePattern: "*.cs"
})Pattern 2: Explore Then Read
Search for what you need:
search_code(pattern="functionName")Get file info:
get_file_info(path="src/module.ts")Read strategically:
read_file(path="src/module.ts", start_line=0)
Pattern 3: Large File Navigation
Check size:
get_file_info(path="big-file.ts")→ "1500 lines"Search within:
search_in_file(path="big-file.ts", pattern="export class")Read around matches: Use line numbers from search to read specific chunks
Pattern 4: Find Files, Then Search
Find files:
find_files(pattern="*Service*.ts")Search within results:
search_code(pattern="constructor", path="src/services")
Common Search Patterns
C# / .NET
// Find any type
"\\b(class|struct|record|interface|enum)\\s+TypeName\\b"
// Find method
"\\b(public|private|protected|internal).*\\s+MethodName\\s*\\("
// Find async methods
"async\\s+(Task|ValueTask)<.*>\\s+\\w+\\s*\\("TypeScript / JavaScript
// Find function/method
"(function|const|let|var)\\s+\\w+\\s*=.*=>|function\\s+\\w+\\s*\\("
// Find class/interface
"(class|interface)\\s+\\w+"
// Find async functions
"async\\s+(function|\\w+\\s*=>|\\(.*\\)\\s*=>)"Python
// Find class
"class\\s+\\w+.*:"
// Find function
"def\\s+\\w+\\s*\\("
// Find async function
"async\\s+def\\s+\\w+"Requirements
Node.js: 22 or higher
ripgrep: Must be installed and available in PATH
Alpine Linux:
apk add ripgrepUbuntu/Debian:
apt install ripgrepmacOS:
brew install ripgrepWindows:
choco install ripgrep
Security
This server implements multiple security layers:
Directory Sandboxing: Only accesses files within allowed directories
Symlink Resolution: Prevents symlink attacks by checking real paths
Path Validation: Blocks path traversal attempts (../, etc.)
Read-Only Docker: Mount volumes as
:rofor read-only access
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watch
# Test locally
node dist/index.js $(pwd)License
MIT
Credits
Built on top of the Model Context Protocol (MCP) SDK and ripgrep.
Available Tools
7 toolsfind_filesC
Find files by name using fast pattern matching.
PATTERN EXAMPLES:
Exact name: "config.json"
Wildcard: "*.config" or "Handler"
Multiple extensions: "*.{ts,tsx,js}"
TIPS:
Use * for any characters
Use ? for single character
Use {a,b,c} for alternatives
Inputs: pattern (required), path.
get_file_infoA
Get file metadata without reading contents. Useful to check size/line count before reading. For large files, provides reading strategy recommendations.
Inputs: path (required).
list_allowed_directoriesB
Show which directories this server can access (security boundaries). No parameters required.
Inputs: no named parameters.
list_directoryB
List contents of a directory with metadata including file sizes and line counts
Inputs: path (required).
read_fileA
Read file contents. For large files (>500 lines), use start_line to read in chunks (e.g., 0, 500, 1000). Each call returns up to 500 lines. Binary files return metadata only.
Inputs: path (required), start_line.
search_codeA
Search for code patterns using ripgrep (very fast). Supports regex patterns and advanced filtering.
PATTERN EXAMPLES:
Exact text: "functionName"
Multiple options: "\b(class|struct|record|interface|enum)\s+TypeName\b" (finds: class TypeName, record TypeName, interface TypeName, etc.)
Regex: "async.Promise<.>" (finds async functions returning Promise)
Any declaration: "\b(public|private|protected)\s+\w+\s+methodName"
COMMON USE CASES:
Find type declaration: "\b(class|struct|interface|record|enum)\s+TypeName\b"
Find method: "\b(public|private|protected|internal).\s+methodName\s\("
Find property: "\bpublic\s+\w+\s+propertyName\s*\{"
Find async methods: "async.*Task<"
Find implementations: ":\s*IInterfaceName\b"
TIPS:
Use \b for word boundaries
Use \s+ for whitespace
Combine alternatives with (opt1|opt2|opt3)
Escape special chars: \( \) \{ \}
Inputs: pattern (required), path, filePattern, caseInsensitive, +5 more.
search_in_fileB
Search for patterns within a specific file using ripgrep. Like Ctrl+F but with regex support. Useful for finding specific sections in a known file.
Inputs: path (required), pattern (required), caseInsensitive, contextLines, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct purposes: find_files locates files by name, get_file_info provides metadata, list_allowed_directories shows accessible directories, list_directory enumerates directory contents, read_file reads file contents, search_code searches across files with regex, and search_in_file searches within a single file. However, search_code and search_in_file could be slightly confused as both involve regex-based searching, though their scopes differ (global vs. file-specific).
All tool names follow a consistent snake_case pattern with clear verb_noun structures: find_files, get_file_info, list_allowed_directories, list_directory, read_file, search_code, and search_in_file. The naming is predictable and readable throughout the set.
With 7 tools, the server is well-scoped for a filesystem domain, covering key operations like finding, listing, reading, and searching files. Each tool serves a specific function without redundancy, making the count appropriate for the intended purpose.
The toolset covers essential filesystem operations such as discovery, metadata retrieval, directory listing, reading, and searching, with good support for large files and regex patterns. A minor gap is the lack of write or modify operations (e.g., create, update, delete files), which might limit full lifecycle management, but the provided tools handle read-only workflows effectively.
Maintenance
Related MCP Connectors
Securely search and manage workspace context files for AI agents and teams.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Artifact store for AI agents — read, write, and search files by path; share by rendered URL.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Large Language Models to safely browse and interact with local file systems through secure directory listing, file reading, and content search capabilities. Built with comprehensive security controls and high-performance handling of large directories and files.1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to intelligently search and explore local file systems using native Unix commands (ripgrep, find, ls) with token-optimized output, automatic pagination, and multi-layer security validation.164 npm2-
- FlicenseBqualityDmaintenanceEnables LLMs to search and read files in local and GitHub repositories, analyze pull request diffs, and grep code content with built-in security protections.6-
- FlicenseBqualityDmaintenanceProvides LLMs with safe, read-only access to local codebases for searching, reading files, and finding function definitions. All source code remains local, ensuring privacy while enabling AI assistants to explore project structures and functionality.4-