Labsco
cyanheads logo

Filesystem MCP Server

★ 42

from cyanheads

Provides AI agents with secure access to local filesystem operations like reading, writing, and managing files and directories.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#devops#git#maps#security

Filesystem MCP Server

Empower your AI agents with robust, platform-agnostic file system capabilities, now with STDIO & Streamable HTTP transport options.

This Model Context Protocol (MCP) server provides a secure and reliable interface for AI agents to interact with the local filesystem. It enables reading, writing, updating, and managing files and directories, backed by a production-ready TypeScript foundation featuring comprehensive logging, error handling, security measures, and now supporting both STDIO and HTTP transports.

Table of Contents

  • Overview

  • Features

  • Installation

  • Configuration

  • Usage with MCP Clients

  • Available Tools

  • Project Structure

  • Development

  • License

Overview

The Model Context Protocol (MCP) is a standard framework allowing AI models to securely interact with external tools and data sources (resources). This server implements the MCP standard to expose essential filesystem operations as tools, enabling AI agents to:

  • Read and analyze file contents.

  • Create, modify, or overwrite files.

  • Manage directories and file paths.

  • Perform targeted updates within files.

Built with TypeScript, the server emphasizes type safety, modularity, and robust error handling, making it suitable for reliable integration into AI workflows. It now supports both STDIO for direct process communication and HTTP for network-based interactions.

Architecture

The server employs a layered architecture for clarity and maintainability:

Copy & paste — that's it
flowchart TB
 subgraph TransportLayer["Transport Layer"]
 direction LR
 STDIO["STDIO Transport"]
 HTTP["HTTP Transport (Express, JWT Auth)"]
 end

 subgraph APILayer["API Layer"]
 direction LR
 MCP["MCP Protocol Interface"]
 Val["Input Validation (Zod)"]
 PathSan["Path Sanitization"]

 MCP --> Val --> PathSan
 end

 subgraph CoreServices["Core Services"]
 direction LR
 Config["Configuration (Zod-validated Env Vars)"]
 Logger["Logging (Winston, Context-aware)"]
 ErrorH["Error Handling (McpError, ErrorHandler)"]
 ServerLogic["MCP Server Logic"]
 State["Session State (Default Path)"]

 Config --> ServerLogic
 Logger --> ServerLogic & ErrorH
 ErrorH --> ServerLogic
 State --> ServerLogic
 end

 subgraph ToolImpl["Tool Implementation"]
 direction LR
 FSTools["Filesystem Tools"]
 Utils["Core Utilities (Internal, Security, Metrics, Parsing)"]

 FSTools --> ServerLogic
 Utils -- Used by --> FSTools
 Utils -- Used by --> CoreServices
 Utils -- Used by --> APILayer
 end

 TransportLayer --> MCP
 PathSan --> FSTools

 classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
 classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
 class TransportLayer,APILayer,CoreServices,ToolImpl layer
 class STDIO,HTTP,MCP,Val,PathSan,Config,Logger,ErrorH,ServerLogic,State,FSTools,Utils component

  • Transport Layer: Handles communication via STDIO or HTTP (with Express.js and JWT authentication).

  • API Layer: Manages MCP communication, validates inputs using Zod, and sanitizes paths.

  • Core Services: Oversees configuration (Zod-validated environment variables), context-aware logging, standardized error reporting, session state (like the default working directory), and the main MCP server instance.

  • Tool Implementation: Contains the specific logic for each filesystem tool, leveraging a refactored set of shared utilities categorized into internal, security, metrics, and parsing modules.

Features

  • Comprehensive File Operations: Tools for reading, writing, listing, deleting, moving, and copying files and directories.

  • Targeted Updates: update_file tool allows precise search-and-replace operations within files, supporting plain text and regex.

  • Session-Aware Path Management: set_filesystem_default tool establishes a default working directory for resolving relative paths during a session.

  • Dual Transport Support:

  • STDIO: For direct, efficient communication when run as a child process.

  • HTTP: For network-based interaction, featuring RESTful endpoints, Server-Sent Events (SSE) for streaming, and JWT-based authentication.

  • Security First:

  • Built-in path sanitization prevents directory traversal attacks.

  • JWT authentication for HTTP transport.

  • Input validation with Zod.

  • Robust Foundation: Includes production-grade utilities, now reorganized for better modularity:

  • Internal Utilities: Context-aware logging (Winston), standardized error handling (McpError, ErrorHandler), request context management.

  • Security Utilities: Input sanitization, rate limiting, UUID and prefixed ID generation.

  • Metrics Utilities: Token counting.

  • Parsing Utilities: Natural language date parsing, partial JSON parsing.

  • Enhanced Configuration: Zod-validated environment variables for type-safe and reliable setup.

  • Type Safety: Fully implemented in TypeScript for improved reliability and maintainability.

Available Tools

The server exposes the following tools for filesystem interaction:

Tool Description set_filesystem_default Sets a default absolute path for the current session. Relative paths used in subsequent tool calls will be resolved against this default. Resets on server restart. read_file Reads the entire content of a specified file as UTF-8 text. Accepts relative (resolved against default) or absolute paths. write_file Writes content to a specified file. Creates the file (and necessary parent directories) if it doesn't exist, or overwrites it if it does. Accepts relative or absolute paths. update_file Performs targeted search-and-replace operations within an existing file using an array of {search, replace} blocks. Ideal for localized changes. Supports plain text or regex search (useRegex: true) and replacing all occurrences (replaceAll: true). Accepts relative or absolute paths. File must exist. list_files Lists files and directories within a specified path. Options include recursive listing (includeNested: true) and limiting the number of entries (maxEntries). Returns a formatted tree structure. Accepts relative or absolute paths. delete_file Permanently removes a specific file. Accepts relative or absolute paths. delete_directory Permanently removes a directory. Use recursive: true to remove non-empty directories and their contents (use with caution!). Accepts relative or absolute paths. create_directory Creates a new directory at the specified path. By default (create_parents: true), it also creates any necessary parent directories. Accepts relative or absolute paths. move_path Moves or renames a file or directory from a source path to a destination path. Accepts relative or absolute paths for both. copy_path Copies a file or directory from a source path to a destination path. For directories, it copies recursively by default (recursive: true). Accepts relative or absolute paths.

Refer to the tool registration files (src/mcp-server/tools/*/registration.ts) for detailed input/output schemas (Zod/JSON Schema).

Project Structure

The codebase is organized for clarity and maintainability:

Copy & paste — that's it
filesystem-mcp-server/
├── dist/ # Compiled JavaScript output (after npm run build)
├── logs/ # Log files (created at runtime)
├── node_modules/ # Project dependencies
├── src/ # TypeScript source code
│ ├── config/ # Configuration loading (index.ts)
│ ├── mcp-server/ # Core MCP server logic
│ │ ├── server.ts # Server initialization, tool registration, transport handling
│ │ ├── state.ts # Session state management (e.g., default path)
│ │ ├── tools/ # Individual tool implementations (one subdir per tool)
│ │ │ ├── readFile/
│ │ │ │ ├── index.ts
│ │ │ │ ├── readFileLogic.ts
│ │ │ │ └── registration.ts
│ │ │ └── ... # Other tools (writeFile, updateFile, etc.)
│ │ └── transports/ # Communication transport implementations
│ │ ├── authentication/ # Auth middleware for HTTP
│ │ │ └── authMiddleware.ts
│ │ ├── httpTransport.ts
│ │ └── stdioTransport.ts
│ ├── types-global/ # Shared TypeScript types and interfaces
│ │ ├── errors.ts # Custom error classes and codes (McpError, BaseErrorCode)
│ │ ├── mcp.ts # MCP related types
│ │ └── tool.ts # Tool definition types
│ ├── utils/ # Reusable utility modules, categorized
│ │ ├── internal/ # Core internal utilities (errorHandler, logger, requestContext)
│ │ ├── metrics/ # Metrics-related utilities (tokenCounter)
│ │ ├── parsing/ # Parsing utilities (dateParser, jsonParser)
│ │ ├── security/ # Security-related utilities (idGenerator, rateLimiter, sanitization)
│ │ └── index.ts # Barrel export for all utilities
│ └── index.ts # Main application entry point
├── .clinerules # Cheatsheet for LLM assistants
├── .dockerignore
├── Dockerfile
├── LICENSE
├── mcp.json # MCP server manifest (generated by SDK or manually)
├── package.json
├── package-lock.json
├── README.md # This file
├── repomix.config.json
├── smithery.yaml # Smithery configuration (if used)
└── tsconfig.json # TypeScript compiler options

For a live, detailed view of the current structure, run: npm run tree (This script might need to be updated if src/scripts/tree.ts was part of the changes).

Developer Note: This repository includes a .clinerules file. This cheat sheet provides your LLM coding assistant with essential context about codebase patterns, file locations, and usage examples. Keep it updated as the server evolves!

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Built with ❤️ and the Model Context Protocol