filesystem

This MCP server provides a virtual filesystem interface that maps real directories into safe, restricted virtual paths. Clients can read, write, list, search, and manipulate files and directories within the allowed directories, while sensitive parts of the host filesystem remain obscured. The server exposes a set of file operations such as read_file, write_file, list_directory, directory_tree, move_file, and search_files, each constrained to the configured allowed paths. Tools are accessed via the MCP protocol, enabling you to query metadata, browse directory structures, and perform bulk operations efficiently. To get started, ensure the server is running with an accessible allowed directory, then connect through an MCP client or the MCP Inspector to issue tool calls and examine results. Use tools/list to explore what can be accessed and tools/call to execute specific operations like directory_tree or read_file.

Prerequisites:

• Node.js and npm (for general MCP tooling) or uvx runtime as described in the repository.
• Access to a machine where you can run the uvx command and bind to the target allowed directory.

1. Install uvx and dependencies (example assumes uvx is available in your PATH):

   • If you already have uvx installed via the project setup, skip to step 2.
   • Otherwise, follow the project repository instructions to install uvx:
     • Ensure you have Python and pip if needed by your platform.
     • Install the uvx runtime and any prerequisites as described in the repository README.

2. Prepare the allowed directory:

   • Create or designate a directory on the host that you want to expose via MCP: mkdir -p /path/to/allowed/directory
   • Ensure the process running the MCP server has read/write access as needed for that directory.

3. Run the MCP server using uvx:

   uvx --from git+https://github.com/dmatscheko/filesystem filesystem /path/to/Allowed/directory

4. (Optional) Run with additional directories:

   uvx --from git+https://github.com/dmatscheko/filesystem filesystem /path/to/allowed/directory1 [/path/to/allowed/directory2 ...]

5. Verify with the MCP Inspector or a client:

   npx -y @modelcontextprotocol/inspector uvx --from git+https://github.com/dmatscheko/filesystem filesystem /path/to/allowed/directory

6. If you need offline usage, clone the repo locally and point uvx at the local path:

   uvx --from file:///full/path/to/folder/filesystem /path/to/allowed/directory

Tips and common issues:

• Always start with list_allowed_directories to confirm what paths are accessible before attempting read/write operations.
• Ensure that the environment where uvx runs has the necessary permissions for the configured allowed directories.
• If you plan to run multiple allowed directories, list them in the uvx command in the order you want them loaded.
• The filesystem MCP server enforces security by restricting operations to allowed directories only; any attempt to access paths outside these directories will fail.
• When using the MCP Inspector, you can validate directory_tree and list to understand the virtual-to-physical mapping for your client calls.
• If you modify code, rebuild according to the repository’s instructions (e.g., uv cache clean) before re-running the server.