Filesystem MCP server for AI agents

The Filesystem MCP Server provides file system operations, analysis, and manipulation capabilities through a standardized Model Context Protocol interface. It serves as a tool for accessing and working with files and directories in a structured way through the MCP protocol.

Installation

Prerequisites

The server requires Node.js and npm to be installed on your system.

Setup Steps

Clone the repository:

git clone <repository-url>
cd filesystem-server

Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```

Configure MCP settings by creating or editing cline_mcp_settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["path/to/filesystem-server/build/index.js"]
    }
  }
}

Usage

Directory Operations

Listing Directory Contents

The list_directory tool provides directory listing with metadata:

// Parameters
{
    "path": "/path/to/directory",    // Required
    "recursive": false               // Optional (default: false)
}

// Result
{
    "entries": [
        {
            "name": "example.txt",
            "path": "/path/to/directory/example.txt",
            "isDirectory": false,
            "size": 1024,
            "created": "2023-01-01T12:00:00Z",
            "modified": "2023-01-02T14:30:00Z",
            "accessed": "2023-01-03T10:15:00Z",
            "mode": "0644"
        },
        // Additional entries...
    ]
}

Creating Directories

Create a new directory with the create_directory tool:

// Parameters
{
    "path": "/path/to/new/directory",
    "recursive": true                // Optional (default: true)
}

File Operations

Reading Files

Read file content using the read_file tool:

// Parameters
{
    "path": "/path/to/file.txt",
    "encoding": "utf8"              // Optional (default: 'utf8')
}

// Result contains the file content as a string

Writing Files

Write content to a file with the write_file tool:

// Parameters
{
    "path": "/path/to/file.txt",
    "content": "Text content to write",
    "encoding": "utf8"               // Optional (default: 'utf8')
}

Appending to Files

Append content to existing files:

// Parameters
{
    "path": "/path/to/file.txt",
    "content": "Text to append",
    "encoding": "utf8"               // Optional (default: 'utf8')
}

Analysis Operations

Text Analysis

Analyze text files with the analyze_text tool:

// Parameters
{
    "path": "/path/to/text/file.txt"
}

// Result
{
    "lineCount": 42,
    "wordCount": 250,
    "charCount": 1500,
    "encoding": "utf8",
    "mimeType": "text/plain"
}

File Hashing

Calculate file hashes using the calculate_hash tool:

// Parameters
{
    "path": "/path/to/file.txt",
    "algorithm": "sha256"            // Optional (default may vary)
}

// Result
{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "algorithm": "sha256"
}

Finding Duplicate Files

Identify duplicate files in a directory:

// Parameters
{
    "path": "/path/to/directory"
}

// Result
{
    "duplicates": [
        {
            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "size": 1024,
            "files": [
                "/path/to/directory/file1.txt",
                "/path/to/directory/file2.txt"
            ]
        }
        // Additional duplicate sets...
    ]
}

Compression Operations

Creating ZIP Archives

Create a ZIP archive from multiple files:

// Parameters
{
    "files": [
        "/path/to/file1.txt",
        "/path/to/file2.txt"
    ],
    "output": "/path/to/archive.zip"
}

Extracting ZIP Archives

Extract the contents of a ZIP archive:

// Parameters
{
    "path": "/path/to/archive.zip",
    "output": "/path/to/extract/directory"
}

Error Handling

The server returns standardized error responses when operations fail:

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

Common error codes include:

-32700: Parse error
-32600: Invalid request
-32601: Method not found
-32602: Invalid parameters
-32603: Internal error

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "filesystem" '{"command":"node","args":["path/to/filesystem-server/build/index.js"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "filesystem": {
            "command": "node",
            "args": [
                "path/to/filesystem-server/build/index.js"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "filesystem": {
            "command": "node",
            "args": [
                "path/to/filesystem-server/build/index.js"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect