Filesystem MCP Server

Empower your AI agents with robust, platform-agnostic file system capabilities.

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, and security measures.

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.

Architecture

The server employs a layered architecture for clarity and maintainability:

• API Layer: Handles MCP communication, validates inputs using Zod, and sanitizes paths.
• Core Services: Manages configuration, logging, 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 shared utilities.

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.
• Security First: Built-in path sanitization prevents directory traversal attacks. Optional base directory restriction enhances security.
• Robust Foundation: Includes production-grade utilities for:
  • Structured, context-aware logging.
  • Standardized error handling with specific error codes.
  • Unique ID generation for request tracing.
  • Input sanitization.
  • Optional rate limiting (util file created but not yet integrated).
• Type Safety: Fully implemented in TypeScript for improved reliability and maintainability.

Installation

Steps

1. Clone the repository:
   git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server
2. Install dependencies:
   npm install
3. Build the project:
   npm run build
   This compiles the TypeScript code to JavaScript in the dist/ directory and makes the main script executable. The executable will be located at dist/index.js.

Configuration

Configure the server using environment variables:

• FS_BASE_DIRECTORY (Optional, Recommended for Security):
  • If set to an absolute path, all file operations performed by the server will be strictly confined within this directory and its subdirectories. This prevents the AI agent from accessing files outside the intended scope.
  • Example: FS_BASE_DIRECTORY=/Users/casey/safe-agent-files
• LOG_LEVEL (Optional):
  • Controls the verbosity of logs. Options: error, warn, info, http, verbose, debug, silly.
  • Defaults to info.
• LOG_DIR (Optional):
  • Specifies the directory where log files (combined.log, error.log) will be stored.
  • Defaults to ./logs relative to the server's execution directory.

Usage with MCP Clients

To allow an MCP client (like an AI assistant) to use this server:

1. Run the Server: Start the server from your terminal:
   node dist/index.js # Or if you are in the project root: # npm start
2. Configure the Client: Add the server to your MCP client's configuration. The exact method depends on the client, but typically involves specifying:
   • Command: node
   • Arguments: The absolute path to the built server executable (e.g., /path/to/filesystem-mcp-server/dist/index.js).
   • Environment Variables (Optional): Set FS_BASE_DIRECTORY, LOG_LEVEL, or LOG_DIR as needed.

   Example MCP Settings (Conceptual):

   { "mcpServers": { "filesystem": { "command": "node", "args": ["/path/to/filesystem-mcp-server/dist/index.js"], "env": { "FS_BASE_DIRECTORY": "/path/to/base/directory", "LOG_LEVEL": "debug" }, "disabled": false, "autoApprove": [] } // ... other servers } }

Once configured and running, the client will detect the server and its available tools.

Available Tools

The server exposes the following tools for filesystem interaction:

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:

For a live, detailed view of the current structure, run: npm run tree

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.