Folder MCP

folder-mcp (Under Development, will be released soon enough)

Model Context Protocol Server for Folder Operations

A Model Context Protocol (MCP) server that provides tools for reading and analyzing folder structures, enabling LLMs to interact with local file systems safely and efficiently.

folder-mcp was created for a simple but powerful purpose: take your local folder and make it accessible to Large Language Models (LLMs) running anywhere. You don't need to upload your files to the cloud or use a third-party service.

it creates RAG (Retrieval-Augmented Generation) capabilities for your local files, allowing LLMs to read, search, and analyze documents in a secure and structured way. This server implements the Model Context Protocol (MCP) standard, allowing LLMs to interact with local file systems through a set of defined tools. This project is designed to work with MCP clients like Claude Desktop, Cursor, VsCode and others, providing a secure and efficient way to access and manipulate files within specified folders.

- Read files from specified folders with path validation
- Security checks to prevent directory traversal attacks
- Support for various file types and encodings

- List all files in a folder recursively
- Search files by name patterns (glob support)
- Get folder information and metadata
- Exclude common directories like node_modules and .git

- Standard Model Context Protocol server implementation
- Works with Claude Desktop and other MCP clients
- Stdio transport for seamless integration
- Structured tool definitions with JSON schemas

- TypeScript implementation with full type safety
- Clear error handling and informative responses
- Simple CLI interface for testing and development

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

folder-mcp uses a centralized configuration system stored inconfig.yamlat the project root. This YAML file contains settings for embeddings, caching, processing, API, logging, and development configurations.

The system supports multiple embedding models with GPU acceleration via Ollama:

# Embedding Model Configuration embeddings: defaultModel: "nomic-v1.5" ollamaApiUrl: "http://127.0.0.1:11434" batchSize: 32 timeoutMs: 30000 models: # Model definitions with dimensions, descriptions, etc. # Cache Configuration cache: defaultCacheDir: "~/.cache/folder-mcp" maxCacheSize: "10GB" cleanupIntervalHours: 24 # Text Processing Configuration processing: defaultChunkSize: 1000 defaultOverlap: 200 maxConcurrentOperations: 10 # Development & Logging options logging: level: "info" format: "json" development: enableDebugOutput: false mockOllamaApi: false

For detailed configuration options, seeCONFIGURATION.md.

This is the foundation release providing secure file system access through MCP. The full vision includes semantic search, embeddings, and intelligent document parsing - seeROADMAP.mdfor the complete development plan.

Coming next:Smart text chunking, semantic embeddings, vector search (see all 30 planned features)

{ "mcpServers": { "folder-mcp": { "command": "node", "args": [ "C:\\Path\\To\\folder-mcp\\dist\\mcp-server.js", "C:\\Path\\To\\folder-mcp" ], "env": {} } } }

⚠️Critical Claude Desktop Integration Note: The MCP protocol requires that ONLY valid JSON-RPC messages go to stdout. Any logging or debugging output to stdout will break the connection. All logs should be redirected to stderr only. See CLAUDE_DESKTOP_SETUP.md for detailed troubleshooting tips.

The server currently provides the following tools:
- get_status- A system status tool that returns processing information to verify connection

- Optional parameter:name- A name to include in the greeting

Read the contents of a specific file within a folder.

- folder_path: Path to the folder containing the file
- file_path: Relative path to the file within the folder

Search for files matching a specific pattern.

- folder_path: Path to the folder to search
- pattern: File pattern (e.g., ".md", ".txt", "config.")

📡 MCP Client (Claude Desktop) ↔ 📞 Stdio Transport ↔ 🖥️ MCP Server ↔ 📁 File System

1. Client Request → 2. Tool Validation → 3. Path Security Check → 4. File Operation → 5. Response

- - All files
- .md- Markdown files only
- /.js- JavaScript files recursively
- config.- Any file starting with "config"

A server for performing filesystem operations such as reading/writing files, managing directories, and searching.