Filesystem MCP server

The MCP Filesystem Server provides secure access to files and directories with intelligent context management, allowing for efficient interaction with large files and complex filesystems. It offers smart partial reading, precise context control, and token-efficient operations designed to work seamlessly with Claude and other AI assistants.

Installation

Prerequisites

Before installing, you'll need to have:

• Python installed on your system
• uv package manager (recommended for installation)

Installing uv

# Install uv using the official installer
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# Or with pipx
pipx install uv

Setting Up MCP Filesystem

# Clone the repository
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# Install dependencies with uv
uv pip sync requirements.txt requirements-dev.txt

Getting Required Paths

You'll need absolute paths for both the repository and any directories you want to access:

# Get the absolute path to the repository
REPO_PATH=$(pwd)
echo "Repository path: $REPO_PATH"

# Get absolute paths to directories you want to access
realpath ~/Documents
realpath ~/Downloads
# Or on systems without realpath:
echo "$(cd ~/Documents && pwd)"

Integration with Claude Desktop

Configuring Claude Desktop

1. Locate your Claude Desktop configuration file:

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

2. Add the MCP Filesystem server configuration:

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/dir1",
        "/absolute/path/to/dir2"
      ]
    }
  }
}

Important: All paths must be absolute (full paths from the root directory).

3. Restart Claude Desktop for the changes to take effect.

Monitoring Server Logs

To debug issues or observe Claude's requests:

# On macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

# On Windows (PowerShell)
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

Running the Server Manually

You can run the server directly with:

# Using uv (recommended)
uv run run_server.py /path/to/dir1 /path/to/dir2

# Or using standard Python
python run_server.py /path/to/dir1 /path/to/dir2

# Example with actual paths
uv run run_server.py /Users/username/Documents /Users/username/Downloads

Command-Line Options

• --transport or -t: Transport protocol (stdio or sse, default: stdio)
• --port or -p: Port for SSE transport (default: 8000)
• --debug or -d: Enable debug logging
• --version or -v: Show version information

Testing with MCP Inspector

For interactive testing and debugging:

# Basic usage
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

# With SSE transport
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080

# With debug output
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

Available Features

Basic File Operations

• Read/write files
• Create directories
• List directory contents
• Move/rename files
• Get file metadata

Line-Targeted Operations

• Read specific line ranges
• Make precise edits with content verification
• Read file heads and tails

Advanced Search

• Search for patterns in files (with ripgrep integration)
• Fine-grained context control and pagination
• Directory tree visualization

Analytics and Reporting

• Calculate directory sizes
• Find duplicate files
• Compare files
• Identify large files or empty directories

Usage Examples

Reading Specific Lines from a File

Tool: read_file_lines
Arguments: {
  "path": "/path/to/file.txt",
  "offset": 99,        # 0-based indexing (line 100)
  "limit": 51,         # Read 51 lines
  "encoding": "utf-8"  # Optional encoding
}

Advanced Search with Context

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # Show 2 lines before each match
  "context_after": 5,        # Show 5 lines after each match
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # Start from the first match
  "results_limit": 20        # Show at most 20 matches
}

Editing Files with Content Verification

Tool: edit_file_at_line
Arguments: {
  "path": "/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "This is the new content for line 15\n",
      "expected_content": "Original content of line 15\n" # Verify content before editing
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # Start considering lines from this offset
  "relative_line_numbers": false,        # Whether line numbers are relative to offset
  "abort_on_verification_failure": true, # Stop on verification failure
  "dry_run": true                        # Preview changes without applying
}

Finding Duplicate Files

Tool: find_duplicate_files
Arguments: {
  "path": "/path/to/search",
  "recursive": true,
  "min_size": 1024,
  "format": "text"
}

Performance Tips

For best performance with search functionality:

• Install ripgrep (rg)
• The server automatically uses ripgrep if available, with a Python fallback

Known Limitations

• Always use absolute paths for consistent results
• Operations on very large directories may take significant time
• The server operates with the same permissions as the user running it
• Path resolution and permissions are strictly enforced for security

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.