cyanheads/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:
mermaid
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.