📂 MCP File Server

MCP File Server is a secure, sandboxed file server providing controlled access to filesystem operations via the Model Control Protocol (MCP). It supports reading, writing, listing, creating, and deleting files and directories within a configurable working directory while enforcing strict security checks.

🎯 Features

Sandboxed operations – all paths are confined to a user‑specified working directory.
Path traversal protection, file‑size limits, and blocked extensions.
Binary support via Base64 encoding for safe transport of non‑text data.
Simple line‑delimited JSON‑RPC protocol suitable for stdin/stdout integration.
Ready‑to‑use with LM Studio through a minimal mcp.json configuration.

📦 Installation & Quick Start

# Clone the repository (if not already done) git clone https://github.com/undici77/MCPFileServer.git cd MCPFileServer # Run the startup script – it creates a virtual environment, # installs dependencies, and starts the server. ./run.sh -d /path/to/working/directory

The script will:

Verify that Python 3 is available.
Create a .venv virtual environment (if missing).
Install required packages (aiofiles).
Start main.py with the supplied working directory.

📌 Tip: Ensure the script has execution permission:
chmod +x run.sh

⚙️ Command‑Line Options

Option

Description

-d

--directory

Path to the

working directory

. If omitted, the server uses the current process directory. The directory must exist and be readable/writable.

🤝 Integration with LM Studio

Add an entry for the file server in your project's mcp.json:

{ "mcpServers": { "file-server": { "command": "/absolute/path/to/MCPFileServer/run.sh", "args": [ "-d", "/absolute/path/to/working/directory" ], "env": { "WORKING_DIR": "." } } } }

Replace the paths with absolute locations on your machine.
Ensure run.sh is executable (chmod +x run.sh) and dependencies are installed.

📡 MCP API Overview

All communication follows JSON‑RPC 2.0 over stdin/stdout.

`initialize`

Sent by the client to obtain server capabilities.

{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} }

The server responds with protocol version, capabilities, and its name/version.

`tools/list`

Retrieves a machine‑readable list of supported tools.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

The response contains an array of tool definitions (name, description, input schema).

`tools/call`

Invokes a specific tool.

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "<tool_name>", "arguments": { … } } }

Note: The key for the tool name is **name**, not tool. This matches the server implementation.

🛠️ Available Tools

Tool	Description
`read_file`	Read a file’s contents (text or binary).
`write_file`	Write text or Base64‑encoded binary data to a file.
`list_files`	List files and directories with optional filtering.
`create_directory`	Create a new sub‑directory (parents created as needed).
`delete_file`	Delete a single file.
`delete_directory`	Remove a directory; optionally force deletion of non‑empty trees.
`search_in_file`	Search for a string in a file or recursively in a directory, returning contextual excerpts.

read_file

Read the contents of a file inside the working directory. Parameters

Name	Type	Required	Description
`path`	string	✅	Relative path to the target file.
`binary`	boolean	❌ (default: `false` )	Set to `true` to read the file as binary; the result is Base64‑encoded.
Example

{ "method": "tools/call", "params": { "name": "read_file", "arguments": { "path": "example.txt", "binary": false } } }

write_file

Write content to a file (creating intermediate directories if needed). Parameters

Name	Type	Required	Description
`path`	string	✅	Relative path of the target file.
`content`	string	✅	Text to write, or Base64‑encoded binary data when `binary=true` .
`binary`	boolean	❌ (default: `false` )	Set to `true` to treat `content` as Base64‑encoded binary.
Example

{ "method": "tools/call", "params": { "name": "write_file", "arguments": { "path": "output.txt", "content": "Hello, world!", "binary": false } } }

list_files

List files and directories under the working directory. Parameters

Name	Type	Required	Description
`extensions`	array of strings	❌	Filter by file extensions (e.g., `[".py", ".txt"]` ). If omitted, all files are listed.
`recursive`	boolean	❌ (default: `true` )	Search sub‑directories recursively when `true` .
`show_empty_dirs`	boolean	❌ (default: `true` )	Include directories that contain no matching files.
Example

{ "method": "tools/call", "params": { "name": "list_files", "arguments": { "extensions": [".py", ".txt"], "recursive": true, "show_empty_dirs": false } } }

The response lists entries prefixed with DIR: or FILE: and includes a summary line.

create_directory

Create a new directory (including any missing parent directories). Parameters

Name	Type	Required	Description
`path`	string	✅	Relative path of the directory to create.
Example

{ "method": "tools/call", "params": { "name": "create_directory", "arguments": { "path": "new_folder/subfolder" } } }

delete_file

Delete a file inside the working directory. Parameters

Name	Type	Required	Description
`path`	string	✅	Relative path of the file to delete.
Example

{ "method": "tools/call", "params": { "name": "delete_file", "arguments": { "path": "temp.txt" } } }

delete_directory

Delete a directory, optionally forcing removal of its contents. Parameters

Name	Type	Required	Description
`path`	string	✅	Relative path of the directory to delete.
`force`	boolean	❌ (default: `false` )	When `true` , deletes non‑empty directories recursively.
Example

{ "method": "tools/call", "params": { "name": "delete_directory", "arguments": { "path": "old_folder", "force": true } } }

search_in_file

Search for a string in a file or recursively in all files within a directory, returning contextual excerpts. Parameters

Name	Type	Required	Description
`path`	string	✅	Relative path to a file or directory.
`search_string`	string	✅	Text to search for.
`context_lines`	integer	❌ (default: `3` )	Number of lines before and after each match to include.
`case_sensitive`	boolean	❌ (default: `false` )	Perform a case‑sensitive search when `true` .
`max_matches`	integer	❌ (default: `50` )	Maximum matches returned per file.
Example

{ "method": "tools/call", "params": { "name": "search_in_file", "arguments": { "path": "log.txt", "search_string": "ERROR", "context_lines": 2, "case_sensitive": false, "max_matches": 10 } } }

The response contains formatted excerpts with line numbers and a summary of total matches.

🔐 Security Features

Path traversal protection – all paths are resolved against the working directory; attempts to escape result in an error.
Blocked extensions & sensitive filenames – files such as .exe, .bat, passwd, etc., are rejected.
File‑size limits – reads/writes exceeding 100 MiB (MAX_FILE_SIZE) are denied.
Null byte and dangerous pattern checks – prevent malformed input attacks.

MCP File Server

📂 MCP File Server

Table of Contents

🎯 Features

📦 Installation & Quick Start

⚙️ Command‑Line Options

🤝 Integration with LM Studio

📡 MCP API Overview

`initialize`

`tools/list`

`tools/call`

🛠️ Available Tools

read_file

write_file

list_files

create_directory

delete_file

delete_directory

search_in_file

🔐 Security Features

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

📂 MCP File Server

Table of Contents

🎯 Features

📦 Installation & Quick Start

⚙️ Command‑Line Options

🤝 Integration with LM Studio

📡 MCP API Overview

initialize

tools/list

tools/call

🛠️ Available Tools

read_file

write_file

list_files

create_directory

delete_file

delete_directory

search_in_file

🔐 Security Features

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

🤝 Integration with LM Studio

`initialize`

`tools/list`

`tools/call`