📂 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.
Table of Contents
🎯 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.jsonconfiguration.
📦 Installation & Quick Start
The script will:
Verify that Python 3 is available.
Create a
.venvvirtual environment (if missing).Install required packages (
aiofiles).Start
main.pywith the supplied working directory.
📌 Tip: Ensure the script has execution permission:
chmod +x run.sh
⚙️ Command‑Line Options
Option | Description |
,
| 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:
Replace the paths with absolute locations on your machine.
Ensure
run.shis 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.
The server responds with protocol version, capabilities, and its name/version.
tools/list
Retrieves a machine‑readable list of supported tools.
The response contains an array of tool definitions (name, description, input schema).
tools/call
Invokes a specific tool.
Note: The key for the tool name is
**name**, nottool. This matches the server implementation.
🛠️ Available Tools
Tool | Description |
| Read a file’s contents (text or binary). |
| Write text or Base64‑encoded binary data to a file. |
| List files and directories with optional filtering. |
| Create a new sub‑directory (parents created as needed). |
| Delete a single file. |
| Remove a directory; optionally force deletion of non‑empty trees. |
| 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 |
| string | ✅ | Relative path to the target file. |
| boolean | ❌ (default:
) | Set to
to read the file as binary; the result is Base64‑encoded. |
Example |
write_file
Write content to a file (creating intermediate directories if needed). Parameters
Name | Type | Required | Description |
| string | ✅ | Relative path of the target file. |
| string | ✅ | Text to write, or Base64‑encoded binary data when
. |
| boolean | ❌ (default:
) | Set to
to treat
as Base64‑encoded binary. |
Example |
list_files
List files and directories under the working directory. Parameters
Name | Type | Required | Description |
| array of strings | ❌ | Filter by file extensions (e.g.,
). If omitted, all files are listed. |
| boolean | ❌ (default:
) | Search sub‑directories recursively when
. |
| boolean | ❌ (default:
) | Include directories that contain no matching files. |
Example |
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 |
| string | ✅ | Relative path of the directory to create. |
Example |
delete_file
Delete a file inside the working directory. Parameters
Name | Type | Required | Description |
| string | ✅ | Relative path of the file to delete. |
Example |
delete_directory
Delete a directory, optionally forcing removal of its contents. Parameters
Name | Type | Required | Description |
| string | ✅ | Relative path of the directory to delete. |
| boolean | ❌ (default:
) | When
, deletes non‑empty directories recursively. |
Example |
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 |
| string | ✅ | Relative path to a file or directory. |
| string | ✅ | Text to search for. |
| integer | ❌ (default:
) | Number of lines before and after each match to include. |
| boolean | ❌ (default:
) | Perform a case‑sensitive search when
. |
| integer | ❌ (default:
) | Maximum matches returned per file. |
Example |
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.
© 2025 Undici77 – All rights reserved.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Provides secure, sandboxed filesystem operations including reading, writing, listing, searching, and managing files and directories within a configurable working directory with strict security controls.