Filesystem

What filesystem MCP server does

The filesystem MCP server exposes local file and directory operations to MCP-compatible AI clients. It accepts initial allowed directories as command-line arguments and restricts operations to those sandbox boundaries. The server is implemented in C# with the official MCP C# SDK and communicates through JSON-RPC over stdin and stdout.

Its operations cover common project and document workflows. Agents can read text files as UTF-8, receive binary files as base64, read selected line ranges, and process several files in one request. They can also create, overwrite, append to, modify, copy, move, rename, and delete files or directories. Directory tools show listings, metadata, and configurable tree views.

Supported document formats can be parsed directly and converted to Markdown files on disk. Conversion is available for individual files and for batches within a directory. The exact formats depend on the included DocumentParsers support.

How it works

The server starts with directories supplied as command-line arguments. Every requested path is checked before an operation runs. Normalization resolves . and .., while directory-aware prefix checks prevent paths outside the sandbox. Symlinks must resolve inside an allowed directory. The validator also blocks NTFS alternate data streams and rejects Windows reserved names.

Clients that support the MCP roots protocol can replace the allowed directories while the process remains running. The new roots replace the previous list rather than extending it. If the client reports no roots, file access is denied. Updates to the allowed-directory set are thread-safe.

Writes use a temporary-file-then-rename approach intended to avoid partially written files. Binary detection determines whether reads return base64 or UTF-8 text. Markdown conversion validates both its source and destination paths and writes the result to disk instead of returning the entire converted document through MCP.

Setup and configuration

Install the .NET global tool with dotnet tool install -g FieldCure.Mcp.Filesystem, or clone the repository and build it with .NET 8.0 or later. A client configuration must launch fieldcure-mcp-filesystem and provide one or more permitted directories as arguments.

For Claude Desktop, place the command and directory arguments under an mcpServers entry. In VS Code, configure the same command under servers; ${workspaceFolder} can be used to allow the current workspace.

Tools and capabilities

Available tools include:

• Read full files, multiple files, or selected line ranges.
• Write, append, and perform plain-text or regular-expression replacements.
• Copy recursively, move, rename, and delete files or directories.
• List directory contents, create directories, inspect metadata, and display directory trees.
• Search for files with glob patterns or search file contents with line numbers.
• Convert supported documents individually or in batches to Markdown files.

Limitations and notes

Text read and write operations target UTF-8. The server detects binary content and returns it as base64, but it does not automatically detect other text encodings. Streaming is not supported for very large files over 100 MB. There is no file-watching or change-notification support, full-text index, multi-file transactional write, HTTP transport, OCR for scanned documents, or cross-platform symlink creation.

The filesystem MCP server supports glob searches and regular-expression replacement, but search is not backed by a full-text index. Document conversion is limited to formats handled by the available document parsers.