mcp-filesystem

The MCP Filesystem Server exposes a secure interface to the local filesystem via the Model Context Protocol (MCP). It defines a File System resource and a rich set of tools for reading, writing, moving, copying, deleting, and inspecting files and directories. This includes operations such as read_file, read_multiple_files, write_file, copy_file, move_file, delete_file, modify_file, list_directory, create_directory, tree, search_files, search_within_files, get_file_info, and list_allowed_directories. These tools enable controlled access to specified directories with path validation and security checks to prevent traversal into unauthorized areas. The server can be run directly, integrated as a library, or exposed via Docker, and can be connected to client applications using MCP JSON configurations similar to the examples provided in the README.

To use the server, configure an MCP mapping for a logical name (for example, filesystem) and supply the command and arguments that start the server. Clients can then call the available tools against the provided path contexts, receiving appropriate metadata, content, and results while honoring the configured allowed directories and any size or MIME-type constraints.

Prerequisites:

• Go installed (1.18+ recommended) for building or installing the Go-based server.
• Optional: Docker if you prefer running via container.

Install (Go install):

1. Ensure GOPATH and GOBIN are set up or use module-aware install: go install github.com/mark3labs/mcp-filesystem-server@latest

2. Verify installation by running the binary or checking the Go module cache. The binary name should be mcp-filesystem-server.

Run directly (standalone):

1. Create a file system access whitelist by specifying one or more allowed directories, e.g. /path/to/allowed/directory
2. Start the server: mcp-filesystem-server /path/to/allowed/directory [additional/allowed/directories ...]

Run with MCP configuration (example):

1. In your MCP configuration, reference the server command and arguments, for example: { "mcpServers": { "filesystem": { "command": "mcp-filesystem-server", "args": ["/path/to/allowed/directory", "/another/allowed/directory"] } } }

Docker (optional):

1. Build or pull the image and run with allowed directories: docker run -i --rm ghcr.io/mark3labs/mcp-filesystem-server:latest /path/to/allowed/directory
2. Example MCP JSON for Docker: { "mcpServers": { "filesystem": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/mark3labs/mcp-filesystem-server:latest", "/path/to/allowed/directory" ] } } }

Security and access tips:

• Always limit the server to a precise set of allowed directories to minimize risk of unauthorized access.
• Use the list_allowed_directories tool (when available) or enforce strict path validation and symlink resolution policies.
• Be mindful of file size limits and encoding formats (text vs binary) when returning content via MCP.
• When running via Docker, consider mounting only the needed host directories to container paths if you need host access (volume bindings).
• If the environment requires persistent state across runs, ensure appropriate write permissions and consider sandboxing or container isolation.
• For lengthy searches or large directories, implement pagination or depth limits to avoid excessive resource use.