local-explorer-mcp

Making Local File System Search Smarter for AI Agents

<p align="center"> <img src="assets/logo.png" alt="local-explorer-mcp - Intelligent File System Explorer for AI" width="150" style="border-radius: 20px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);" /> </p>

An MCP (Model Context Protocol) server for intelligent local file system exploration using native Unix/Linux commands (inspired by octocode-mcp).

✨ This project used its own prompts to generate AGENTS.md and ARCHITECTURE.md

🚧 Ongoing Research Project - Please share your feedback and suggestions via GitHub Issues

---

🎯 Built-in AI Prompts

Two powerful prompts to auto-generate comprehensive documentation:

📐 generate_architecture_markdown - Create ARCHITECTURE.md

Auto-generates complete architecture documentation by exploring your codebase:

• Identifies project type, language, and scale
• Maps entry points, core components, and system boundaries
• Discovers architectural patterns and key abstractions

Perfect for: New contributors, architecture reviews, understanding complex codebases

🤖 generate_agents_markdown - Create AGENTS.md

Auto-generates AI-friendly guidance for coding assistants:

• Discovers and merges existing agent configs (CLAUDE.md, .cursorrules, etc.)
• Maps file permissions (edit, ask first, never touch)
• Extracts setup commands, testing workflows, and style guidelines
• Documents code style, commit format, and PR requirements

Perfect for: AI-assisted development, team onboarding, consistent coding practices

---

💡 Why Use This?

Smart local codebase research - faster and more efficient than traditional file reading:

• Research Your Code - Understand complex codebases, find functions/classes, trace implementations
• Investigate Dependencies - Debug issues in node_modules, explore third-party code, detect bugs
• Smart Workspace Search - Pattern-based discovery, time-based filtering, metadata search
• Token Efficient - Automatic pagination, minification, and smart chunking
• Native Performance - Leverages ripgrep, find, ls for blazing-fast searches
• Security First - Multi-layer validation prevents path traversal and command injection
• Agent Optimized - Purpose-built workflows with decision trees for AI assistants

---

Table of Contents

• Built-in AI Prompts
• Why Use This
• Installation
• Tools Overview
• Usage Examples
• Security Features
• Performance Tips
• Development
• Troubleshooting

---

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• ripgrep (required for local_ripgrep tool):
  • ✅ Already available in Claude Code and Cursor
  • macOS: brew install ripgrep
  • Ubuntu/Debian: apt-get install ripgrep
  • Windows: choco install ripgrep
  • Installation guide

Quick Install

<details> <summary>Claude Code</summary>

claude mcp add local-explorer-mcp npx local-explorer-mcp@latest

</details>

<details> <summary>Claude Desktop</summary>

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "local-explorer-mcp": {
      "command": "npx",
      "args": ["local-explorer-mcp@latest"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}

</details>

<details> <summary>Cursor</summary>

Click to install:

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">

Or manually edit your Cursor MCP settings and add:

{
  "mcpServers": {
    "local-explorer-mcp": {
      "command": "npx",
      "args": ["local-explorer-mcp@latest"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

</details>

Environment Variables

• WORKSPACE_ROOT (required): Project root directory. Defaults to current working directory.
• DEBUG (optional): Set to "true" for detailed logging
• CACHE_TTL (optional): Cache duration in seconds (default: 900)
• MEMORY_LIMIT (optional): Max memory in MB (default: 100)

---

🚀 How It Works

Once installed, AI assistants can automatically:

1. Explore directories - View project structure, find entry points
2. Search code patterns - Find functions, classes, or any text
3. Filter by metadata - Locate files by name, size, or modification time
4. Read efficiently - Extract specific sections without loading entire files

---

🛠️ Tools Overview

4 Unix-powered tools for efficient file system research:

Tool	Purpose	Unix Command	Best For
local_view_structure	Directory exploration	ls / fs.readdir	Project structure, finding entry points
local_ripgrep	Pattern search	ripgrep	Finding functions, classes, TODOs
local_find_files	File discovery	find	Metadata filtering (name, size, time)
local_fetch_content	Content reading	fs.readFile	Efficient file reading with pagination

All tools support bulk operations and smart pagination.

---

1. local_view_structure - Directory Exploration

Explore directory structure with sorting and filtering options.

Key Features:

• Tree or list view
• Sort by name, size, time, or extension
• Filter by file patterns
• Control depth (1-5 levels)
• Include/exclude hidden files

Use Cases:

• Understand project organization
• Find large or recently modified files
• Identify entry points and key directories

Workflow: Start with depth=1 for overview → drill down into specific directories → sort by size/time as needed

---

2. local_ripgrep - Pattern Search

Fast code search using ripgrep. Find functions, classes, or patterns across your codebase in milliseconds.

Key Features:

• Discovery mode (files only) or detailed mode (matches with context)
• Regex and fixed-string search
• Smart case, case-insensitive, or whole-word matching
• Filter by file type or patterns
• Exclude directories (node_modules, etc.)
• Pagination for large results

Use Cases:

• Find function/class definitions and usages
• Locate TODO comments or error messages
• Understand code patterns across projects
• Quick file discovery

Workflow: Discovery mode (filesOnly=true) → detailed search with context → read full file if needed

---

3. local_find_files - Advanced File Discovery

Find files by name, size, modification time, or permissions.

Key Features:

• Name matching (case-sensitive/insensitive, regex, multiple patterns)
• Time filters (modifiedWithin, modifiedBefore, accessedWithin)
• Size filters (sizeGreater, sizeLess)
• File attributes (type, permissions, executable, empty)
• Exclude directories
• Control depth and result limits

Use Cases:

• Find config files (*.config.js, .env)
• Locate large files
• Track recent modifications
• Discover executable scripts
• Combine multiple criteria

Examples:

• Recent TypeScript: name="*.ts", modifiedWithin="7d"
• Large files: sizeGreater="1M"
• Executables: executable=true, type="f"

---

4. local_fetch_content - Smart Content Reading

Read files efficiently with automatic optimization and pagination.

Key Features:

• Full file or pattern-based extraction (matchString)
• Automatic minification (removes comments/whitespace)
• Pagination for large files
• Context control (lines around matches)

Use Cases:

• Read config files
• Extract specific functions/classes
• Follow up on search results
• Handle large files with pagination

Reading Modes:

• fullContent=true - Entire file (small files)
• matchString="functionName" - Extract specific sections (most efficient)
• matchStringContextLines=20 - Control surrounding context

Integration: Use with ripgrep → find patterns → extract with matchString

---

💡 Usage Examples

Common Workflows

Understanding a New Codebase:

1. View structure (sortBy size) → Find entry points → Search patterns → Read key files

Finding and Fixing Bugs:

1. Search error message → Find recent files → Extract function/class

Code Refactoring:

1. Find all usages (filesOnly) → Get detailed matches → Read affected sections

Performance Analysis:

1. Find large files → Check recent modifications → Search TODO/FIXME comments

---

🔒 Security Features

Multi-layer security with command whitelisting, path validation, and resource limits.

Core Protections

Command Whitelisting: Only rg, find, ls allowed

Path Protection:

• Workspace-restricted operations
• Path traversal prevention
• Symlink validation
• Absolute path resolution

Sensitive File Filtering (automatic):

• Secrets: .env, *.pem, *.key, credentials.json
• Dependencies: node_modules/, .yarn/
• Build artifacts: dist/, build/, *.min.js
• VCS: .git/, .svn/
• IDE: .vscode/, .idea/

Resource Limits:

• Timeout: 30s (configurable)
• Output: 10MB max (configurable)
• Memory: 100MB (configurable)
• Auto-pagination for token limits

Injection Prevention:

• Direct command execution (no shell)
• Argument validation and escaping
• No command chaining

---

⚡ Performance Tips

Token Optimization:

1. Start with discovery (filesOnly mode)
2. Use pattern matching over full files
3. Enable minification for code files
4. Process bulk operations in parallel
5. Use automatic pagination

Caching: 15-min TTL, LRU eviction, automatic

Memory Management: 100MB default, per-operation tracking, auto-cleanup

---

🐛 Troubleshooting

ripgrep not found:

# Install ripgrep
brew install ripgrep              # macOS
apt-get install ripgrep           # Ubuntu/Debian
choco install ripgrep             # Windows

Permission denied: Check WORKSPACE_ROOT permissions with ls -la

Path outside workspace: Verify WORKSPACE_ROOT is set correctly, avoid symlinks outside workspace

Server not starting:

1. Check Node.js >= 18.0.0
2. Clear cache: npm cache clean --force
3. Check MCP config syntax
4. View logs: Claude Desktop → Help → Show Logs

Token limit exceeded: Use filesOnly=true, pagination, matchString instead of fullContent

Slow performance: Use specific patterns, limit scope, exclude large dirs, use depth=1

Debug Mode: Set DEBUG="true" in env vars for detailed logging

Get Help: GitHub Issues

---

📄 License

MIT License - see LICENSE.md for details.

---

🙏 Acknowledgments

• Inspired by octocode-mcp research methodologies
• Built on Model Context Protocol by Anthropic
• Powered by ripgrep

---

npm: local-explorer-mcp