Folder

Folder MCP is a Model Context Protocol (MCP) server that lets you securely expose your local folders to Large Language Models. It provides Retrieval-Augmented Generation (RAG) capabilities so an LLM can read, search, and analyze your files without uploading them to the cloud. You control which folders are accessible and how the server answers questions about their contents.

How to use

You connect an MCP client to the Folder MCP server over a stdio transport. The server exposes tools to read files, list files, search by patterns, and obtain folder metadata. To use it, configure your MCP client to start the server locally, then invoke tools through the client in your normal workflow. The secure path validation and directory exclusions protect against common attack vectors, so only files inside the allowed folders are accessible.

How to install

Prerequisites: You need Node.js and npm installed on your system.

Clone the project, install dependencies, and build the server.

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

Configuration and security notes

Folder MCP uses a centralized configuration file to manage embedding models, caching, processing, API access, and logging. It excludes common directories like node_modules and .git from all operations and validates file paths to prevent directory traversal. If you need to tailor how folders are scanned or how results are chunked, adjust the processing and cache sections of the configuration.

Here is a representative MCP configuration snippet that you would use in your MCP client to connect to the local Folder MCP server via stdio.

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

Troubleshooting tips

Ensure stdout contains only valid JSON-RPC messages when communicating with an MCP client. Redirect all logs to stderr to avoid breaking the connection. If you encounter permission errors, verify that the server has access to the configured folders and that excluded directories (like node_modules and .git) are properly ignored.

Notes and ongoing development

The project is in active development with a roadmap that includes advanced text chunking, semantic embeddings, and vector search in future releases. You will see enhancements around multi-format parsing, real-time updates, and deeper MCP integration over time.

Available tools

read_file

Read the contents of a specific file within a folder. Parameters: folder_path (path to the folder), file_path (relative path to the file).

list_files

List all files in a folder recursively. Parameters: folder_path.

search_files

Search for files matching a specific pattern. Parameters: folder_path, pattern (e.g., *.md, *.txt).

get_folder_info

Get information about a folder, including file count and metadata. Parameters: folder_path.

get_status

A system status tool that returns processing information to verify connection. Optional parameter: name to include in the greeting.