MCP File Tools

What the MCP File Tools MCP server does

MCP File Tools MCP server provides agent access to local directories that are explicitly authorized when the process starts. Its capabilities cover ordinary file operations, project inspection, text search, source navigation, state verification, backups, and encoding management. The repository identifies the current implementation as Scripthold and describes it as derived from the original mcp-file-tools project.

The server is intended for local workspaces rather than remote storage services. Workspace boundaries are enforced using canonical-root containment, with additional handling for Windows reparse points and junctions. Missing paths and traversal behavior are validated before operations proceed.

How it works

A stdio client starts the executable with one or more authorized directories as arguments. Those startup roots are authoritative. A roots-capable stdio client may provide dynamic roots only when no directory arguments are supplied at launch.

The server can also run over Streamable HTTP. HTTP mode uses bearer authentication, defaults to loopback-oriented operation, and exposes an MCP endpoint alongside liveness and readiness endpoints. Non-loopback exposure requires additional security configuration, including TLS or a trusted proxy boundary.

Mutating operations can use a preview-and-apply pattern. Proposed changes may be checked against exact fingerprints and conflict conditions before being written. The tool catalog also includes backup creation, restoration, comparison-related state checks, and explicit backup cleanup operations.

Setup and configuration

Published platform binaries are available from the repository’s release page and can be checked against the supplied checksums. Building from source requires Go; the documented build flow runs the test suite and builds the executable from ./cmd/scripthold.

For local stdio use, configure an MCP client with the executable path and authorized workspace arguments. For HTTP use, provide a bearer token and an address such as 127.0.0.1:8765; requests must include the token in the Authorization header. The documented container example mounts a project at /data, runs with a read-only root filesystem, drops capabilities, and uses an unprivileged user.

Tools and capabilities

MCP File Tools MCP server exposes tools for:

• Reading one or multiple text files and writing or editing files.
• Previewing and applying packaged multi-file patches.
• Listing directories, generating trees, and retrieving file metadata.
• Searching files with text queries, regular expressions, or path-oriented operations.
• Inspecting source symbols, outlines, relations, and bounded source context.
• Computing digests and fingerprints, then verifying expected workspace state.
• Storing, restoring, and garbage-collecting local backups.
• Detecting encodings and line endings, converting text encodings, and applying conversions.

The implementation documents support for 168 registered text encodings, including UTF-32 little-endian and big-endian forms, with conservative handling when detection is ambiguous.

Limitations and notes

The server only reaches directories authorized through its startup or supported roots configuration. HTTP should not be exposed beyond loopback without reviewing the project’s security guidance and configuring an appropriate authentication and transport boundary.

The repository lists GPL-3.0 licensing. Detailed schemas, parameters, limits, and error behavior are maintained in the project’s TOOLS.md reference, so clients should consult that file before relying on particular argument names or operation limits. The tool names include both preview and apply variants; callers should not assume that a preview changes files.