Fsext Mcp Server Python

A full-featured secure MCP server for local file system operations, with built-in image processing, OCR and media tools. Fully compliant with the official Model Context Protocol specification, offering standardized request/response schemas, large-file streaming I/O, multi-transport remote deployment, and comprehensive text search & replace functionality for LLM agent integration.

- Full File & Directory Management: Support file creation, deletion, copy, move, metadata query, existence check; full directory tree recursion copy and move with overwrite safety controls.
- Streaming File Read/Write: Integrate full text reading, segmented line-based text reading, chunked binary reading, text/binary overwriting and appending writing, optimized to avoid loading entire large files into memory.
- Powerful Search & Replace: Support directory-wide recursive file content search, single/multi-file contextual matching with configurable pre/post matching lines, regular expression matching, case-insensitive search, and in-place text replacement with match count statistics.
- Image Processing Tools: Built-in high-performance image toolkit powered by Pillow, including resize (aspect ratio lock + canvas padding support), crop, and arbitrary-angle clockwise rotation.
- Native Tesseract OCR Recognition: Reliable text extraction from images dependent on local Tesseract binary installation. No WASM fallback; an empty binary path argument will not trigger alternative JS-based OCR engines. Multi-language tessdata resource support with configurable binary and data paths.
- Strict Input Validation & Unified Response Format: Every tool enables strictadditionalProperties: falseschema validation to block unexpected input fields. All operations share a universal success/error wrapping structure for consistent client parsing.
- Multi-Transport Support: Compatible with official standard MCP transports:stdio(local desktop client integration),sse(legacy lightweight remote stream), and Streamable HTTP (modern bidirectional remote streaming transport).
- Workspace Security Isolation: Provide--lock-rootdirectory restriction capability. All file/directory operations are strictly confined to the specified root workspace to prevent unauthorized cross-directory path escape attacks.

Quick Start: Run directly with uvx (No pre-installation required)

uvxautomatically pulls the published PyPI package and launches an isolated runtime environment, eliminating manual dependency installation or virtual environment setup.

# Default stdio mode, unrestricted full filesystem access uvx fsext-mcp-server # Lock all operations to a dedicated workspace (production security recommended) uvx fsext-mcp-server --lock-root /your/workspace

# Stdio mode with workspace isolation uvx fsext-mcp-server --transport stdio --lock-root /your/workspace # Remote SSE streaming service uvx fsext-mcp-server --transport sse --host 0.0.0.0 --port 8000 --lock-root /your/workspace # Modern Streamable HTTP remote service uvx fsext-mcp-server --transport http --host 0.0.0.0 --port 8000 --lock-root /your/workspace

2. Integrate FsExt tools with LLM frameworks

No pre-deployment on host machines required;uvxdynamically instantiates the server when an MCP client establishes a connection.

Client config example (Claude Desktop / Cursor MCP json)

{ "mcpServers": { "fsext": { "command": "uvx", "args": [ "fsext-mcp-server", "--lock-root", "/your/workspace" ], "env": {"PYTHONUTF8": "1"} } } }

LangChain / LangGraph core integration snippet

Session lifecycle limitations exist within officiallangchain-mcp-adapters; complete stable long-connection logic requires extra adapter customization. Below is the standard minimal connection template:

# Core config: Connect to FsExt MCP via uvx stdio transport server_config = { "fsext": { "transport": "stdio", "command": "uvx", "args": ["fsext-mcp-server", "--lock-root", r"/your/workspace"], "env": {"PYTHONUTF8": "1"} } } # Load all exposed filesystem MCP tools client = MultiServerMCPClient(server_config) async with client.session("fsext") as session: mcp_tools = await load_mcp_tools(session) # Bind loaded MCP tools to LLM instance for agent workflows llm = ChatOpenAI(base_url="your-local-llm-api").bind_tools(mcp_tools)

Traditional installation & launch via pip

# Default stdio local mode fsext-mcp-server-py fsext-mcp-server # Short alias fsext-py fsext # Secure workspace locked mode fsext --lock-root /your/workspace # Remote SSE streaming server fsext --transport sse --port 8000

Local source repository development setup

It is recommended to useuvfor fast, deterministic environment deployment:

# Clone official source repository git clone https://github.com/kurtzhi/fsext-mcp-server-python cd fsext-mcp-server-python # Install full runtime + dev dependencies uv sync

- chardet: Automatic text file encoding detection
- Pillow: Core image processing backend for resize, crop, rotate pipelines
- python-magic: Accurate cross-platform file MIME type identification
- fastmcp: Official Python MCP server framework
- uvicorn / starlette: HTTP/SSE transport server runtime
- pydantic: Strict schema validation for all tool input parameters
- tesseract: Native bindings for local Tesseract OCR binary

The server supports three official MCP transport modes and flexible workspace root isolation configuration via CLI flags.

1. Default Local Stdio Mode (for Claude Desktop / Cursor AI Clients)

2. Stdio Mode with Mandatory Workspace Lock (Secure Local Agent Use)

uv run -m fsext --lock-root /your/workspace/path

uv run -m fsext --transport sse --host 0.0.0.0 --port 8000

- SSE long-lived stream subscription channel (server event push):http://<host>:<port>/sse
- Client JSON-RPC request submission channel:http://<host>:<port>/messages

- Transport type: SSE
- Connection address input:http://127.0.0.1:8000/sse

4. Standard Streamable HTTP Remote Transport (Modern Bidirectional)

uv run -m fsext --transport http --host 0.0.0.0 --port 8000

Single shared entry point for both client requests and server streaming:http://<host>:<port>/mcp

- Transport type: Streamable HTTP
- Connection address input:http://127.0.0.1:8000/mcp

5. SSE vs Streamable HTTP Transport Feature Comparison

All MCP tools share an identical top-level wrapping JSON structure for both successful execution and runtime failure states. Every tool’s business payload is nested within theinfosub-object under the rootresfield.

{ "res": { "success": boolean, "info": object } }

- success: Global operation status flag

- true: Tool logic executed without exceptions;infocontains tool-specific return data
- false: Operation failed (workspace escape block, missing file, IO error, invalid input schema, permission denied, etc.)
- Success mode (success: true): Custom structured business payload unique to each tool
- Failure mode (success: false): Fixed standardized error object with machine-readable error code and human-readable explanation

"info": { "code": "ERROR_CODE_IDENTIFIER", "message": "Detailed human-readable failure description" }

1. Successful Response Sample (fs_list_directory)

{ "res": { "success": true, "info": { "paths": [ "/tmp/tests/test_util.py", "/tmp/tests/__init__.py", "/tmp/tests/img/cochem_castle.jpg" ] } } }

2. Failure Response Sample (Workspace Path Escape Restriction)

{ "res": { "success": false, "info": { "code": "WORKSPACE_ESCAPE_FORBIDDEN", "message": "Access restricted: Path /tmp/test2 is outside allowed workspace /tmp/tests" } } }

All tools enforce workspace root isolation and fully follow the standardized input/output schema definitions listed below.

All tool input schemas enableadditionalProperties: falsestrict validation to reject unrecognized parameters and prevent malicious path injection vectors.

Description: Scan target directory recursively or shallowly, return filtered absolute filesystem path list with file-type and extension filtering controls.Parameters:

- source_dir(string, required): Root directory path for scanning
- recursive(boolean, required): Enable full recursive traversal of all subdirectories
- only_files(boolean, required): Filter output to return only regular files, exclude directories
- file_extension(string, optional, default=""): Filter results to files matching the specified suffix extensionSuccess Response Payload:

{ "res": { "success": true, "info": { "paths": ["/absolute/path/file1.txt", "/absolute/path/file2.py"] } } }

Description: Recursively copy an entire directory tree, with configurable overwrite behavior for pre-existing target directories.Parameters:

- source_dir(string, required): Source directory tree path
- copy_dest_dir(string, required): Target output directory path
- overwrite(boolean, optional, default=false): Clear and overwrite existing destination directory contentsSuccess Response Payload:

{ "res": { "success": true, "info": {} } }

Description: Atomically move an entire directory tree to a new target path. Fails immediately if destination exists unless overwrite is explicitly enabled to avoid accidental data loss.Parameters:

- source_dir(string, required): Source directory path
- dest_dir(string, required): Target directory path
- overwrite(boolean, optional, default=false): Allow overwriting conflicting destination directoriesSuccess Response Payload: Emptyinfoobject wrapper with success flag.

Description: Create a new text file, automatically generate missing parent directories, support configurable text encoding and initial file content.Parameters:

- file_path(string, required): Target absolute file path
- content(string, optional, default=""): Initial text content written to the new file
- charset(string, optional, default="utf-8"): Text encoding enum value (full charset list below) Supported Charset Enum Values:utf-8,utf-16,latin-1,iso-8859-1,cp1252,Windows-1252,gbk,gb2312,shift_jis,euc_jp,euc_krSuccess Response Payload: Emptyinfoobject wrapper with success flag.

Description: Permanently delete a single regular file only; rejects directory path inputs to block mass recursive deletion risks.Parameters:

- file_path(string, required): Target regular file absolute pathSuccess Response Payload: Emptyinfoobject wrapper with success flag.

Description: Copy a single file while retaining original filesystem metadata, with configurable overwrite for conflicting target files.Parameters:

- source_file_path(string, required): Source file absolute path
- dest_file_path(string, required): Target output file absolute path
- overwrite(boolean, optional, default=false): Overwrite pre-existing destination fileSuccess Response Payload: Emptyinfoobject wrapper with success flag.

Description: Atomically move a single file to a new absolute path, with configurable overwrite behavior for conflicting destination files.Parameters:

- source_file_path(string, required): Source file absolute path
- dest_file_path(string, required): Target file absolute path
- overwrite(boolean, optional, default=false): Allow overwriting conflicting destination filesSuccess Response Payload: Emptyinfoobject wrapper with success flag.

Description: Retrieve complete metadata for files or directories, with optional SHA-256 cryptographic digest calculation for integrity verification.Parameters:

- file_path(string, required): Target filesystem entry absolute path
- calc_digest(boolean, optional, default=false): Compute SHA-256 hash of file contentsSuccess Response Payload:

{ "res": { "success": true, "info": { "absolute_path": "C:\\Users\\zhigu\\Documents\\My Games\\fsext-mcp-server\\pyproject.toml", "is_readable": true, "is_writable": true, "size": 1672, "is_regular_file": true, "is_directory": false, "is_symbolic_link": false, "creation_millis": 1782288135574.7114, "last_modified_millis": 1782279393020.1187, "last_access_millis": 1782644004556.3462, "sha256_digest": "59614cf5f8ecff38de37637f1d5b6f607d885bd277815786f5ce4bb2ee5b73a6" } } }

Description: Lightweight existence check for any filesystem entry (file or directory) without loading full metadata.Parameters:

- file_path(string, required): Target absolute path to verifySuccess Response Payload:

{ "res": { "success": true, "info": { "exists": true } } }

Description: Read the complete text content of a target file with user-specified text encoding.Parameters:

- file_path(string, required): Target text file absolute path
- charset(string, optional, default="utf-8"): Text encoding enum valueSuccess Response Payload:

{ "res": { "success": true, "info": { "content": "complete-text-file-content-here" } } }

Description: Stream segmented text reading optimized for large files; skip leading lines and limit total read lines to avoid memory overload.Parameters:

- file_path(string, required): Target text file absolute path
- lines_to_skip(integer, required, minimum=0): Number of initial lines to skip during reading
- max_lines_to_read(integer, required, minimum=0): Maximum total lines to extract from file
- line_separator(string, optional, default="\n"): Line break delimiter character
- charset(string, optional, default="utf-8"): Text encoding enum valueSuccess Response Payload:

{ "res": { "success": true, "info": { "lines_count": 5, "content": "segmented-text-content-block" } } }

Description: Chunked streaming read for binary files; returns Base64 encoded byte payloads for safe network JSON-RPC transmission with end-of-stream marker detection.Parameters:

- file_path(string, required): Target binary file absolute path
- bytes_to_skip(integer, required, minimum=0): Number of leading bytes to skip before reading chunk
- max_bytes_to_read(integer, required, minimum=0): Maximum byte length to read in single chunkSuccess Response Payload:

{ "res": { "success": true, "info": { "data_base64": "base64-encoded-binary-byte-data", "raw_bytes_length": 5, "end_of_stream": true } } }

Description: Write UTF or multi-encoded text content to target file, supporting full overwrite or append-only write modes.Parameters:

- file_path(string, required): Target output file absolute path
- text(string, required, minLength=1): Raw text content to persist
- append(boolean, optional, default=false): Append mode flag (false = overwrite entire file)
- charset(string, optional, default="utf-8"): Text encoding enum valueSuccess Response Payload: Emptyinfoobject wrapper with success flag.

Description: Decode Base64 encoded binary payload and write raw bytes to target file, supporting append mode for multi-chunk binary uploads.Parameters:

- file_path(string, required): Target output file absolute path
- base64_data(string, required, minLength=1): Base64 encoded raw binary byte payload
- append(boolean, optional, default=false): Append binary data to end of file (false = overwrite)Success Response Payload: Emptyinfoobject wrapper with success flag.

4. Content Search & In-Place Replace Tools

Description: Recursively scan directory tree and return absolute paths of all files containing matching target text pattern; support regex matching, case insensitivity, and file extension filtering.Parameters:

- dir_path(string, required): Root directory for recursive content scan
- recursive(boolean, required): Enable full subdirectory recursion
- search_term(string, required): Plain text keyword or regular expression pattern
- is_regex(boolean, optional, default=false): Treat search_term as regex pattern when true
- ignore_case(boolean, optional, default=true): Case-insensitive pattern matching
- file_extension(string, optional, default=""): Filter scanned files by extension suffix
- charset(string, optional, default="utf-8"): Text encoding enum value for file parsing