mcp-filesystem

The MCP Filesystem Server provides controlled access to your local filesystem for AI models via the Model Context Protocol. It is built with TypeScript and Node.js and exposes a set of file-system related tools, such as reading and writing files, listing directories, creating directories, and querying metadata—all within predefined, safe directories. You can run it locally or via an npm/npx invocation, making it easy to integrate into your existing MCP workflows. To use, point the server at directories you want to allow access to and then interact with the exposed tools (read_file, write_file, list_directory, directory_tree, etc.) through the MCP SDK, a Claude-like UI, or any MCP-compatible client.

Prerequisites:

• Node.js >= 18.0.0
• Git
• pnpm >= 8.0.0
• Docker (optional)
• Docker Compose (optional)

1. Clone the repository:

git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
cd mcp-filesystem

2. Install dependencies:

pnpm install

3. Build the application (typical for TypeScript projects):

pnpm build

4. Run the server locally (specify a directory you want to allow access to):

pnpm start /path/to/allowed/directory

5. Alternatively, install and run via the npm package (global):

npm install -g @gabrielmaialva33/mcp-filesystem
mcp-filesystem /path/to/allowed/directory

6. Docker usage (optional):

# Build the image
docker build -t gabrielmaialva33/mcp-filesystem .

# Run with a mounted data directory
docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

7. Docker Compose (optional):

mkdir -p data
docker-compose up -d

Tips and common considerations:

• When using Docker, you can mount multiple directories into targets under /projects as described in the README to control access scopes.
• You can create a config.json to store access paths and server options, then start the server with --config=config.json as shown in the Docker example.
• The server exposes a rich set of tools for filesystem operations (read_file, write_file, list_directory, etc.) and system capabilities like get_metrics and execute_command. New curl_request tool will be available in a future release (v1.2.0).
• If using NPX, ensure you pass the exact allowed directories as arguments after the package name to restrict access appropriately.
• For Claude Desktop or other MCP clients, you can embed the mcpServers configuration in your client config to point to this server.