# folder-mcp

> Provides MCP access to local folders for secure filesystem operations including listing, reading/writing files with sandboxing and path validation. Key features include recursive listing, glob search, MIME detection, configurable roots, and exclusion patterns for .git/node_modules. Use cases: AI agents persisting data autonomously, local RAG pipelines, code generation/editing; vs direct FS libraries: MCP enables agentic workflows with standardized tools.

- **URL:** https://github.com/okets/folder-mcp
- **Category:** Databases & Storage MCP Servers
- **Tags:** Filesystem Access, Local Storage, Sandboxed Fs, File Io, Read Write, Directory Exploration
- **Updated:** 2026-04-25 12:27
- **Canonical page:** https://mcpserver.ever.works/items/folder-mcp

## Details

## Overview

folder-mcp implements the Model Context Protocol (MCP) standard to allow LLMs to interact with local folders securely via stdio transport.

## Features

- **Secure File Access**: Path validation, prevents directory traversal, supports various file types and encodings.
- **File System Operations**: Recursive listing, glob-based searching, folder metadata.
- **Exclusions**: Automatically skips node_modules, .git, and cache directories.
- **MCP Tools**:
  - `get_status`: System status check.
  - `read_file`: Read file contents by relative path.
  - `search_files`: Find files by pattern (e.g., '*.md').
  - `list_files`: Recursive file listing.
  - `get_folder_info`: Folder stats and metadata.
- TypeScript with full type safety, clear error handling.

## Installation

```
git clone https://github.com/okets/folder-mcp.git
cd folder-mcp
npm install
npm run build
```

## Configuration

Uses `config.yaml` for embeddings (Ollama support: nomic-v1.5, mxbai-large, etc.), caching, text processing, logging, and dev options.

## Usage

Configure in MCP clients like Claude Desktop:

```json
{
  "mcpServers": {
    "folder-mcp": {
      "command": "node",
      "args": ["dist/mcp-server.js", "/path/to/folder-mcp"],
      "env": {}
    }
  }
}
```

Note: Logs to stderr only for stdio compatibility.

## Pricing

Free and open-source under MIT License.

## Current Status

Version 1.0: Basic MCP server (13/30 features). Upcoming: Semantic search, embeddings, vector search.

---

_This Markdown mirror is generated by Ever Works for AI agents. The canonical HTML page is at https://mcpserver.ever.works/items/folder-mcp._