local-filesystem-mcp-server

harshaga55/local-filesystem-mcp-server

3.2

If you are the rightful owner of local-filesystem-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Local Filesystem MCP Server is a Python-based server that provides secure access to essential filesystem operations across macOS, Linux, and Windows.

Tools
6
Resources
0
Prompts
0

Local Filesystem MCP Server

Python-based Model Context Protocol (MCP) server that safely exposes essential filesystem tools (list, search, copy, move) on macOS, Linux, and Windows.

Features

  • Directory listing with recursion control, hidden file visibility, and symlink handling.
  • Glob-style search with case sensitivity toggles and directory/file matching options.
  • Copy and move helpers that support files, directories, and symlinks (with cross-device fallbacks).
  • Operations are scoped to the working directory by default to keep access constrained.
  • Optional Azure Document Intelligence tooling for text extraction and analytics.

Prerequisites

Setup

poetry install

Run the MCP server over stdio (compatible with Claude Desktop, VS Code, Cursor, etc.):

poetry run start --transport stdio

Configuration

The server boots with any environment variables defined in a local .env file (placed beside this README). Variables already present in the shell take precedence.

Server basics

Key environment variables (all optional) live in .env:

  • MCP_SERVER_PORT — listen port for HTTP transports (defaults to 8000).
  • MCP_TRANSPORT — choose stdio, sse, or streamable-http when launching via CLI.
  • MCP_SERVER_LOG_LEVEL — adjust FastMCP logging (INFO by default).
  • MCP_FS_ROOTS — optional list of additional root directories the tools may access.

When MCP_FS_ROOTS is set, provide one or more absolute paths separated by the OS path delimiter (: on macOS/Linux, ; on Windows). If omitted, the server limits access to the working directory it was started from.

Transport selection

All FastMCP transports are supported:

  • stdio (default) keeps compatibility with desktop IDE clients.
  • sse (Server Sent Events) exposes streaming endpoints suitable for HTTP clients.
  • streamable-http exposes the Streamable HTTP transport introduced in MCP 1.19.

Set MCP_TRANSPORT in your .env (or pass --transport on the command line) to choose which transport instance to launch. When an HTTP transport is selected (sse or streamable-http), the server listens at http://127.0.0.1:<port>/, using MCP_SERVER_PORT when provided.

MCP_TRANSPORT=sse
MCP_SERVER_PORT=9000

Example run commands:

# Read transport choice from .env
poetry run start

# Override transport at runtime
poetry run start --transport streamable-http

Azure Document Intelligence (optional)

Document analysis tools are registered only when the Azure credentials below are present (either in .env or the shell):

  • AZURE_DOCUMENT_ENDPOINT
  • AZURE_DOCUMENT_KEY
  • AZURE_DOCUMENT_MODEL_ID (defaults to prebuilt-layout if omitted)

If these variables are missing, the server keeps running but skips the Azure-backed tools so nothing sensitive is exposed.

Quick Azure setup:

  1. If you don’t already have keys, sign in (az login or Azure Portal) using the subscription that owns your Document Intelligence resource.
  2. Create or locate a Document Intelligence (a.k.a. Form Recognizer) resource in the desired region.
  3. Grab the endpoint URL and one of the access keys from the Keys & Endpoint blade (az cognitiveservices account keys list --name <name> --resource-group <rg> works too).
  4. Populate .env with the endpoint/key (and optional model id), then restart the server.

If you already possess a valid endpoint and key from someone else on your team, skip the login steps—just drop those values straight into .env and the tools will activate.

Install the client library when you enable these tools (either package works):

poetry add azure-ai-documentintelligence
# or, for the older SDK
poetry add azure-ai-formrecognizer

Available Tools

ToolPurposeKey Arguments
files_list_directoryList directory entries (optionally recursive).path?, recursive=false, include_hidden=false, follow_symlinks=false, max_depth=5, limit=200
files_findGlob search for files/directories under a path.pattern, path?, include_hidden=false, case_sensitive=true, match_files=true, match_directories=true, max_depth=25, limit=500
files_copyCopy files/directories/symlinks.source, destination, overwrite=false, recursive=true
files_moveMove (cut) files/directories/symlinks.source, destination, overwrite=false, recursive=true
analysis_word_count*Get word/character counts via Azure Document Intelligence.path, model_id?
analysis_extract_text*Retrieve up to 8k chars of extracted text.path, model_id?, max_characters=8000

*Registered only when Azure credentials are available.

Resources:

  • file://{path} — expose file metadata (and a UTF-8 preview when possible).

Each tool returns structured JSON plus a text summary, making the responses friendly for both user interfaces and automated agents.

Integrating with MCP Clients

Most MCP clients accept a stdio command. Configure your client to run poetry run start (or the equivalent venv path) and connect using the stdio transport option. Clients that support streamable HTTP/SSE can instead target the printed local URL when you launch poetry run start --transport sse (or streamable-http).

Learn more about MCP at modelcontextprotocol.io.