Filesystem MCP Server

by bsmi021

Integrations

  • Included in development dependencies for code linting within the file system operations.

  • Included in development dependencies for running tests on the file system operations and analysis capabilities.

  • Used for visualizing the architecture of the MCP server in documentation.

Filesystem MCP Server

A Model Context Protocol (MCP) server implementation providing file system operations, analysis, and manipulation capabilities through a standardized tool interface.

Architecture

The server is built on the MCP SDK and organized into distinct layers:

Components

  • Server Layer: Handles MCP protocol communication and tool dispatch
  • Tool Registry: Manages tool registration and execution
  • Operations Layer: Implements core functionality
  • File System Interface: Provides safe file system access

Installation

  1. Clone the repository:
git clone <repository-url> cd filesystem-server
  1. Install dependencies:
npm install
  1. Build the server:
npm run build
  1. Configure MCP settings (cline_mcp_settings.json):
{ "mcpServers": { "filesystem": { "command": "node", "args": ["path/to/filesystem-server/build/index.js"] } } }

Tool Reference

Directory Operations

list_directory

Lists directory contents with metadata.

interface ListDirectoryParams { path: string; // Directory path recursive?: boolean; // List recursively (default: false) } interface ListDirectoryResult { entries: { name: string; path: string; isDirectory: boolean; size: number; created: string; modified: string; accessed: string; mode: string; }[]; }
create_directory

Creates a new directory.

interface CreateDirectoryParams { path: string; // Directory path recursive?: boolean; // Create parent directories (default: true) }

File Operations

read_file

Reads file content with encoding support.

interface ReadFileParams { path: string; // File path encoding?: string; // File encoding (default: 'utf8') }
write_file

Writes content to a file.

interface WriteFileParams { path: string; // File path content: string; // Content to write encoding?: string; // File encoding (default: 'utf8') }
append_file

Appends content to a file.

interface AppendFileParams { path: string; // File path content: string; // Content to append encoding?: string; // File encoding (default: 'utf8') }

Analysis Operations

analyze_text

Analyzes text file properties.

interface AnalyzeTextParams { path: string; // File path } interface AnalyzeTextResult { lineCount: number; wordCount: number; charCount: number; encoding: string; mimeType: string; }
calculate_hash

Calculates file hash using specified algorithm.

interface CalculateHashParams { path: string; // File path algorithm?: 'md5' | 'sha1' | 'sha256' | 'sha512'; // Hash algorithm } interface CalculateHashResult { hash: string; algorithm: string; }
find_duplicates

Identifies duplicate files in a directory.

interface FindDuplicatesParams { path: string; // Directory path } interface FindDuplicatesResult { duplicates: { hash: string; size: number; files: string[]; }[]; }

Compression Operations

create_zip

Creates a ZIP archive.

interface CreateZipParams { files: string[]; // Files to include output: string; // Output ZIP path }
extract_zip

Extracts a ZIP archive.

interface ExtractZipParams { path: string; // ZIP file path output: string; // Output directory }

Error Handling

The server uses standard MCP error codes:

enum ErrorCode { ParseError = -32700, InvalidRequest = -32600, MethodNotFound = -32601, InvalidParams = -32602, InternalError = -32603 }

Error responses include:

  • Error code
  • Human-readable message
  • Additional context when available

Example error:

{ "code": -32602, "message": "File not found: /path/to/file.txt" }

Development

Project Structure

src/ ├── operations/ # Core operations implementation ├── tools/ # MCP tool definitions and handlers ├── __tests__/ # Test suites ├── index.ts # Entry point ├── server.ts # MCP server setup ├── types.ts # Type definitions └── utils.ts # Utility functions

Running Tests

Run the test suite:

npm test

Run with coverage:

npm run test:coverage

Development Mode

Run in watch mode:

npm run watch

Code Quality

Lint the codebase:

npm run lint

Type check:

npm run type-check

Dependencies

Core dependencies:

  • @modelcontextprotocol/sdk: MCP server implementation
  • file-type: File type detection
  • mime-types: MIME type lookup
  • crypto-js: File hashing
  • archiver: ZIP creation
  • extract-zip: ZIP extraction
  • iconv-lite: Text encoding
  • chardet: Encoding detection

Development dependencies:

  • typescript: Type system
  • jest: Testing
  • eslint: Linting
  • prettier: Formatting
  • ts-node: TypeScript execution
  • nodemon: Development server

Contributing

  1. Fork the repository
  2. Create your feature branch
  3. Write tests for new features
  4. Ensure all tests pass
  5. Submit a pull request

License

MIT

-
security - not tested
A
license - permissive license
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A Model Context Protocol server that provides file system operations, analysis, and manipulation capabilities through a standardized tool interface.

  1. Architecture
    1. Components
  2. Installation
    1. Tool Reference
      1. Directory Operations
      2. File Operations
      3. Analysis Operations
      4. Compression Operations
    2. Error Handling
      1. Development
        1. Project Structure
        2. Running Tests
        3. Development Mode
        4. Code Quality
      2. Dependencies
        1. Contributing
          1. License

            Related MCP Servers

            • A
              security
              A
              license
              A
              quality
              A Model Context Protocol server that provides tools for code modification and generation via Large Language Models, allowing users to create, modify, rewrite, and delete files using structured XML instructions.
              Last updated -
              12
              Python
              MIT License
              • Linux
              • Apple
            • A
              security
              A
              license
              A
              quality
              A Model Context Protocol server that enables enhanced file system operations including reading, writing, copying, moving files with streaming capabilities, directory management, file watching, and change tracking.
              Last updated -
              12
              6
              TypeScript
              MIT License
            • -
              security
              A
              license
              -
              quality
              A custom Model Context Protocol server that gives Claude Desktop and other LLMs access to file system operations and command execution capabilities through standardized tool interfaces.
              Last updated -
              22
              Python
              Apache 2.0
              • Apple
              • Linux
            • -
              security
              A
              license
              -
              quality
              A Model Context Protocol server that provides secure and intelligent interaction with files and filesystems, offering smart context management and token-efficient operations for working with large files and complex directory structures.
              Last updated -
              5
              Python
              MIT License
              • Apple
              • Linux

            View all related MCP servers

            ID: hfidyfcfcx