Filesystem MCP

Overview

Filesystem MCP is a Model Context Protocol server that gives AI agents secure access to read and write files on the local filesystem. It enables agents to read code, configuration files, documentation, and more — making it essential for coding assistants.

Key Features

📁 File Operations

• Read Files: Read any accessible file on the filesystem
• Write Files: Create and modify files
• List Directories: Browse directory structures
• Search Files: Find files by name or pattern
• Get File Info: View file metadata (size, modified date, etc.)

🔒 Security Features

• Allowed Paths: Restrict access to specific directories
• Read-Only Mode: Prevent file modifications
• Path Validation: Prevent directory traversal attacks
• Audit Logging: Track all file operations

🔍 Search Capabilities

• Glob Patterns: Search using **/*.py, src/**/*.tsx, etc.
• Text Search: Search for content within files
• Recursive Search: Search through entire directory trees

Installation

# Using npx (recommended)
npx -y @modelcontextprotocol/server-filesystem /allowed/path1 /allowed/path2

# Interactive mode (prompts for paths)
npx -y @modelcontextprotocol/server-filesystem

Configuration

Basic Setup

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    }
  }
}

Multiple Allowed Paths

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/documents",
        "/path/to/other/directory"
      ]
    }
  }
}

Read-Only Mode

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/safe/read/only/path"],
      "env": {
        "READ_ONLY": "true"
      }
    }
  }
}

With Environment Variables

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/project/path"],
      "env": {
        "ALLOWED_DIRS": "/project/path,/shared/path",
        "READ_ONLY": "false"
      }
    }
  }
}

Available Tools

Tool	Description
read_file	Read the contents of a file
read_files	Read multiple files at once
write_file	Create or overwrite a file
edit_file	Make edits to an existing file
list_directory	List contents of a directory
create_directory	Create a new directory
delete_file	Delete a file
delete_directory	Delete a directory (recursive)
move_file	Move or rename a file
search_files	Search for files by name pattern
get_file_info	Get metadata about a file

Usage Examples

Read a File

Read the file at /projects/my-app/src/main.py

Search for Files

Find all Python files in the project

Agent searches using pattern: **/*.py

Read Multiple Files

Read all the configuration files in the config directory

Agent reads: config/*.json, config/*.yaml, etc.

Write a New File

Create a new file at /projects/my-app/README.md with this content:
# My Project
This is a sample project...

Edit an Existing File

Edit /projects/my-app/src/utils.py to add a new function

List Directory Contents

What files are in the src/components directory?

Get File Information

How large is the database file and when was it last modified?

Integration with AI Agents

Claude Desktop for Coding

Filesystem MCP is essential for coding assistants:

Claude: "Let me look at your code to understand the project structure..."
[List reads src/, lib/, config/]
Claude: "I see you're using a Next.js project with TypeScript..."
[Reads package.json, tsconfig.json]
Claude: "Now let me check the main component..."
[Reads src/app/page.tsx]

Cursor / Windsurf / Zed

All MCP-compatible code editors benefit from Filesystem MCP:

• Code Understanding: Read project files to understand context
• Refactoring: Read and modify files safely
• Documentation: Read and create documentation
• Debugging: Read logs and configuration files

Custom Agent Integration

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to Filesystem MCP
server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # List directory
        contents = await session.call_tool(
            "list_directory",
            arguments={"path": "/path/to/project/src"}
        )
        
        # Read file
        content = await session.call_tool(
            "read_file",
            arguments={"path": "/path/to/project/src/main.py"}
        )
        
        # Search files
        results = await session.call_tool(
            "search_files",
            arguments={"pattern": "**/*.test.py"}
        )

Security Considerations

Allowed Paths

⚠️ Important: Only grant access to directories the agent needs:

// ❌ Too permissive
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/"]

// ✅ Appropriate
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects/my-app"]

Read-Only Mode

For agents that only need to read files:

"env": {
  "READ_ONLY": "true"
}

Path Traversal Prevention

The server validates all paths to prevent:

• ../../etc/passwd attacks
• Access to paths outside allowed directories
• Symlink-based escapes

Pros

• ✅ Essential for Coding: Critical for code understanding
• ✅ Flexible: Works with any file type
• ✅ Secure: Path validation and allowed directories
• ✅ Rich Toolset: Read, write, search, list, delete
• ✅ Easy Setup: Simple npx command with paths
• ✅ Cross-Platform: Works on Windows, macOS, Linux

Cons

• ❌ Security Risk: Must carefully configure allowed paths
• ❌ No Binary Support: Best for text files
• ❌ Large Files: May struggle with very large files
• ❌ No Version Control: Doesn't integrate with git
• ❌ Manual Setup: Must specify allowed directories

When to Use

Choose Filesystem MCP when:

• You need agents to read code and project files
• You want agents to create or modify files
• You're building a coding assistant
• You need to search through project files

Consider alternatives when:

• You only need to read from specific files (use read-only mode)
• You need git integration (use dedicated git MCP)
• You're working with binary files (limited support)

Resources

• GitHub: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
• MCP Servers Repo: https://github.com/modelcontextprotocol/servers
• Documentation: https://modelcontextprotocol.io/introduction
• Security Best Practices: https://modelcontextprotocol.io/docs/security

Comparison

Feature	Filesystem MCP	Git MCP	Editor MCP
File Read	✅ Yes	⚠️ Limited	✅ Yes
File Write	✅ Yes	⚠️ Limited	✅ Yes
Search	✅ Yes	❌ No	⚠️ Limited
Git Integration	❌ No	✅ Yes	⚠️ Limited
Security	⚠️ Manual config	✅ Built-in	✅ Built-in
Best For	General files	Version control	Editor-specific

---

Last updated: May 2026