Is it safe to give AI access to my files?

Yes, when configured properly. The Filesystem MCP server uses a sandboxed approach - AI can only access directories you explicitly specify. It cannot escape to parent directories or access files outside the allowed paths.

Can AI access files outside the allowed directories?

No. The server enforces strict path validation. Even if AI tries to use '../' or absolute paths to escape, the server blocks access to anything outside your specified directories.

Can I make it read-only?

Yes! The Filesystem MCP server can be configured in read-only mode, preventing any file modifications. This is useful for code review or analysis workflows.

How many directories can I allow?

You can specify any number of directories. Each is passed as a separate argument to the server. The AI will have access to all of them.

What happens if I grant access to my home directory?

It's not recommended as it exposes all your personal files, credentials, and sensitive data. Always grant access only to specific project or document folders.

Can AI delete my files?

The default Filesystem MCP includes a delete operation. If this concerns you, use read-only mode or carefully review AI suggestions before confirming destructive operations.

Does it work with symbolic links?

Yes, but the server validates that the resolved path is still within allowed directories. You can't use symlinks to escape the sandbox.

Can I use Filesystem MCP with Cursor for coding?

Absolutely! This is one of the best use cases. Point it at your project directory and AI can read your entire codebase for context-aware assistance. It also works with Claude Desktop, VS Code + Copilot, and other MCP clients.

Filesystem MCP Server: Give AI Secure Access to Your Files

TL;DR - Filesystem MCP Quick Start

Core MCP server - Let AI read and write your local files securely.

🏡 December 2025: Filesystem MCP is now part of the Agentic AI Foundation under the Linux Foundation, ensuring continued open-source development. For an introduction to MCP, see the MCP Introduction guide.

Quick Setup:

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

What you can do:

📖 Read: Access any file in allowed directories
✏️ Write: Create and update files
🔍 Search: Find files by pattern
📋 List: Browse directory contents
📦 Move: Rename and relocate files
❌ Delete: Remove files (with caution!)

Example conversation:

You: Read my package.json and tell me what dependencies I'm using

Claude: I'll read your package.json...

        Your project has these dependencies:
        - react: ^18.2.0
        - typescript: ^5.0.0
        - tailwindcss: ^3.3.0
        ...
        
        And these dev dependencies:
        - @types/react: ^18.0.0
        - eslint: ^8.0.0
        ...

💡 Security Note: Always specify only the directories you need. Never grant access to your home folder or system directories.

🤖 2025 Update: Filesystem MCP works with all major AI platforms including Claude, ChatGPT, GitHub Copilot, and Gemini.

Why Filesystem MCP Matters

Before MCP, sharing code with AI meant endless copy-pasting:

Without Filesystem MCP	With Filesystem MCP
Copy file, paste into chat	”Read src/auth.ts”
Copy output, paste into file	”Write the fix to src/auth.ts”
Describe file structure	”List all files in src/“
Manually search files	”Find all files importing lodash”

Use Cases

Use Case	How It Helps
Code Review	AI reads entire codebase for context
Documentation	AI generates docs from source code
Refactoring	AI understands file relationships
Bug Finding	AI searches across all files
Note Taking	AI reads/writes markdown notes
Data Analysis	AI reads CSVs and data files

Security Model Explained

Understanding security is critical before granting file access. For more on responsible AI usage, see the Understanding AI Safety, Ethics, and Limitations guide.

The Sandbox

┌─────────────────────────────────────────────────────────────┐
│                     YOUR FILESYSTEM                          │
│                                                              │
│  /Users/you/                                                 │
│  ├── projects/           ◄─── ✅ Allowed (you configured)   │
│  │   ├── my-app/                                            │
│  │   └── tools/                                              │
│  ├── documents/notes/    ◄─── ✅ Allowed (you configured)   │
│  ├── .ssh/              ◄─── ❌ BLOCKED                     │
│  ├── .aws/              ◄─── ❌ BLOCKED                     │
│  ├── private/           ◄─── ❌ BLOCKED                     │
│  └── ...                                                     │
│                                                              │
│  /etc/                   ◄─── ❌ BLOCKED (system files)     │
│  /var/                   ◄─── ❌ BLOCKED (system files)     │
└─────────────────────────────────────────────────────────────┘

Key Security Features

Feature	How It Protects You
Explicit paths only	Must declare each allowed directory
No parent traversal	`../` can’t escape the sandbox
Validated absolute paths	Can’t trick with path manipulation
Symlink validation	Resolved paths must be in allowed dirs
Read-only option	Prevent any modifications

What AI CAN’T Do

Even with Filesystem MCP:

❌ Access files outside allowed directories
❌ Read your SSH keys, passwords, or credentials
❌ Access system configuration files
❌ Execute files or run code
❌ Access other users’ files
❌ Change file permissions

Installation & Configuration

Prerequisites

Node.js v18+ (check with node --version)
MCP-compatible client (Claude Desktop, ChatGPT, Cursor, VS Code + Copilot, Gemini, etc.)

Claude Desktop Setup

Add to claude_desktop_config.json:

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

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

Multiple Directories

Add as many directories as needed:

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

Cursor Setup

For project-level access, add to .cursor/mcp.json:

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

💡 Tip: Using . gives access to the current workspace only.

Read-Only Mode

For maximum safety, use read-only access:

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

Windows Paths

Use forward slashes or escaped backslashes:

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

Verify Installation

Restart your AI client and test:

You: List the files in my projects folder

Claude: Here are the files in /Users/yourname/projects:
        
        📁 my-app/
        📁 website/
        📁 scripts/
        📄 notes.md
        📄 todo.txt

Available Tools

The Filesystem MCP server provides these file operations:

Read Operations

Tool	Description	Example Prompt
`read_file`	Read entire file content	”Read the package.json”
`read_multiple_files`	Read several files at once	”Read all files in src/components/“
`list_directory`	List files and subdirectories	”What files are in the src folder?”
`get_file_info`	Get file metadata (size, dates)	“When was this file last modified?”
`search_files`	Search by filename pattern	”Find all .ts files”

Write Operations

Tool	Description	Example Prompt
`write_file`	Create or overwrite a file	”Create a README.md”
`create_directory`	Make a new folder	”Create a tests folder”
`move_file`	Move or rename a file	”Rename old.js to new.js”

Search Operations

Tool	Description	Example Prompt
`search_files`	Find files by glob pattern	”Find all *.test.ts files”
`list_allowed_directories`	Show which dirs are accessible	”Which directories can you access?”

Configuration Best Practices

✅ Do’s

Practice	Example
Grant specific project folders	`/Users/me/projects/my-app`
Use read-only for sensitive data	`--read-only` flag
Separate work and personal	Different server configs
Review paths before adding	No credential folders
Start minimal, expand if needed	Begin with one folder

❌ Don’ts

Practice	Risk
Grant home directory	Exposes everything: keys, configs, passwords
Include .env file locations	Leaks API keys and secrets
Include cloud sync folders	Might contain sensitive synced data
Use /tmp or world-writable dirs	Security vulnerabilities
Grant system directories	Could expose system config

Safe Directory Examples

// ✅ Good configurations

// Single project
"args": ["-y", "...", "/Users/me/projects/my-app"]

// Multiple specific projects
"args": ["-y", "...", 
  "/Users/me/projects/frontend",
  "/Users/me/projects/backend"
]

// Notes directory (read-only)
"args": ["-y", "...", "--read-only", "/Users/me/notes"]

// ❌ Bad configurations

// Home directory - TOO BROAD
"args": ["-y", "...", "/Users/me"]

// SSH keys - NEVER
"args": ["-y", "...", "/Users/me/.ssh"]

// AWS credentials - NEVER  
"args": ["-y", "...", "/Users/me/.aws"]

Practical Workflows

Workflow 1: Code Review

You: Review all TypeScript files in src/auth/ for security issues

Claude: I'll read and analyze the auth module...

For more on AI-assisted code review, see the AI-Powered IDEs Comparison guide.

[Reads src/auth/login.ts] [Reads src/auth/session.ts] [Reads src/auth/password.ts]

Security Review of src/auth/

⚠️ Issues Found:

login.ts:45 - Password logged to console

console.log('Password:', password); // REMOVE THIS

session.ts:78 - Session token in localStorage Consider using httpOnly cookies instead.
password.ts:12 - Using MD5 for hashing Upgrade to bcrypt or argon2.

✅ Good Practices Found:

Rate limiting on login attempts
Session expiration implemented
CSRF tokens used


### Workflow 2: Documentation Generation

```text
You: Read all the source files in src/utils/ and create 
     comprehensive API documentation

Claude: I'll analyze the source files...

        [Reads 8 files in src/utils/]
        
        I've created documentation for your utilities:
        
        ---
        # Utils API Documentation
        
        ## formatDate(date, format?)
        Formats a Date object into a string.
        
        **Parameters:**
        - `date`: Date - The date to format
        - `format`: string (optional) - Format string, default 'YYYY-MM-DD'
        
        **Returns:** string
        
        **Example:**
        ```typescript
        formatDate(new Date(), 'MM/DD/YYYY') // '12/24/2024'

debounce(fn, delay)

…

Would you like me to write this to docs/API.md?

You: Yes, save it

Claude: ✅ Written to docs/API.md


### Workflow 3: Find and Fix Pattern

```text
You: Find all files using the deprecated moment.js library 
     and show me what needs to be updated

Claude: Searching for moment.js usage...

        **Files using moment.js:**
        
        1. **src/utils/dates.ts** (12 imports)
           ```typescript
           import moment from 'moment';
           // Used for: formatting, parsing, diff

src/components/Calendar.tsx (3 imports)

import moment from 'moment';
// Used for: date manipulation

tests/date.test.ts (5 imports)

import moment from 'moment';
// Used for: test assertions

Recommended Migration: Replace with date-fns or native Date methods.

Would you like me to:

Show specific migration examples for each file?
Create a migration plan document?
Start replacing one file as an example?


### Workflow 4: Project Scaffolding

```text
You: Create a new Express API project structure in projects/new-api 
     with TypeScript config, proper folder structure, and a basic 
     health check endpoint

Claude: I'll set up the project structure...

        ✅ Created projects/new-api/
        ✅ Created package.json with dependencies
        ✅ Created tsconfig.json
        ✅ Created src/
        ✅ Created src/index.ts (main entry)
        ✅ Created src/routes/health.ts
        ✅ Created src/middleware/errorHandler.ts
        ✅ Created tests/
        ✅ Created .gitignore
        ✅ Created README.md
        
        **Project Structure:**

new-api/ ├── src/ │ ├── index.ts │ ├── routes/ │ │ └── health.ts │ └── middleware/ │ └── errorHandler.ts ├── tests/ ├── package.json ├── tsconfig.json ├── .gitignore └── README.md


To get started:
```bash
cd projects/new-api
npm install
npm run dev


### Workflow 5: Smart Note Search

For more on CLI-based AI workflows, see the [CLI Tools for AI guide](/tech-articles/cli-tools-for-ai/).

```text
You: Search through my notes folder and find everything related 
     to "quarterly planning"

Claude: Searching notes...

        **Found 4 notes mentioning quarterly planning:**
        
        1. **notes/2024/q4-planning.md**
           - Created: Oct 15, 2024
           - Summary: Q4 goals, budget allocation, team OKRs
        
        2. **notes/meetings/leadership-sync-oct.md**
           - Created: Oct 20, 2024
           - Relevant section: "Q4 resource planning discussion"
        
        3. **notes/ideas/2025-roadmap.md**
           - Created: Nov 5, 2024
           - Mentions: Q1 2025 quarterly planning timeline
        
        4. **notes/templates/quarterly-review.md**
           - Template for quarterly reviews
        
        Would you like me to:
        - Show the full content of any of these?
        - Create a summary combining all quarterly planning info?
        - Find related notes about "OKRs" or "budgets"?

Example Prompts

Reading Files

# Single file
"Read the README.md in my project"
"Show me the contents of src/config/database.ts"
"Open the .env.example file and list all required variables"

# Multiple files
"Read all TypeScript files in src/components/"
"Show me both package.json and package-lock.json"
"Read the test files for the auth module"

# With analysis
"Read package.json and identify outdated dependencies"
"Read all route files and list the API endpoints"
"Read src/types/ and explain the data models"

Writing Files

# Create new files
"Create a new file called utils/helpers.ts with these functions..."
"Write a README for this project based on the code"
"Create a .env.example with all the required variables"

# Update existing
"Add a new function to utils/strings.ts"
"Update the version number in package.json to 2.0.0"
"Add error handling to the main index.ts"

# With generation
"Create comprehensive JSDoc comments for all functions in utils/"
"Write a CONTRIBUTING.md based on the project structure"
"Create TypeScript types based on the API response examples"

File Organization

# Listing and searching
"List all files in the src directory"
"Find all test files (*.test.ts, *.spec.ts)"
"Show the project structure as a tree"
"Find all files larger than 100KB"

# Moving and organizing
"Rename config.js to config.ts"
"Move all utility functions to a utils/ folder"
"Create a backup directory and copy important files there"

# Cleanup
"Find all TODO comments across the codebase"
"List files that haven't been modified in 6 months"
"Find duplicate code in the components folder"

Analysis Prompts

# Code quality
"Analyze the error handling patterns across all files"
"Find functions longer than 50 lines"
"Check for console.log statements that should be removed"

# Documentation
"List all files missing JSDoc comments"
"Check if all exported functions have documentation"
"Find all API endpoints and verify they're documented"

# Security
"Search for hardcoded API keys or secrets"
"Find files that might contain sensitive data"
"Check for SQL queries that might be vulnerable to injection"

Troubleshooting

Issue: “Path not allowed”

Symptoms: AI can’t access a file or directory

Solutions:

Cause	Solution
Path not in config	Add directory to server args
Using relative path	AI should use full path within allowed dir
Symlink escaping sandbox	Resolve symlink and add actual path
Path typo	Check exact spelling and case

You: Why can't you read ~/Downloads/file.txt?

Claude: I can only access these directories:
        - /Users/yourname/projects
        - /Users/yourname/notes
        
        /Users/yourname/Downloads is not in my allowed list.
        Would you like to add it to your MCP configuration?

Issue: “File not found”

Symptoms: AI says file doesn’t exist

Solutions:

Cause	Solution
File really doesn’t exist	Check location
Wrong case (on case-sensitive systems)	Use exact filename case
Path confusion	Use full path from allowed root

Issue: “Permission denied”

Symptoms: OS blocks file access

Solutions:

Cause	Solution
File owned by another user	Check file permissions
Directory not readable	Run `chmod +r` on directory
System restrictions (macOS)	Grant Full Disk Access if needed

Issue: “Read-only mode prevents writes”

Symptoms: Can’t create or modify files

Solutions:

// Remove --read-only flag to enable writes
{
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/Users/me/projects"  // No --read-only
  ]
}

Combining with Other MCPs

Filesystem + GitHub

Read local code, create PRs:

You: Read the changes in src/auth/ and create a GitHub PR 
     with a description of the updates

Claude: [Uses Filesystem to read local files]
        [Uses GitHub to create PR]
        
        Created PR #45: "Refactor authentication module"
        URL: https://github.com/...

Filesystem + Memory

Remember project context:

You: Read my project and remember its architecture for future questions

Claude: [Uses Filesystem to read project]
        [Uses Memory to store understanding]
        
        I've analyzed your project and stored:
        - Architecture: React frontend + Express API
        - Key patterns: Redux for state, Axios for API calls
        - Test setup: Jest with React Testing Library
        
        I'll remember this context for our future conversations.

Filesystem + Playwright

Test apps, save results:

You: Run E2E tests on my app and save the results to test-report.md

Claude: [Uses Playwright to run tests]
        [Uses Filesystem to save report]
        
        Test run complete!
        - 24/25 tests passed
        - 1 failure in checkout flow
        
        Report saved to test-report.md

Advanced: Multiple Configs

Separate Work and Personal

{
  "mcpServers": {
    "work-files": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/work"
      ]
    },
    "personal-notes": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--read-only",
        "/Users/me/notes"
      ]
    }
  }
}

Project-Specific Access

Create .cursor/mcp.json in each project:

// In my-frontend/.cursor/mcp.json
{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

This keeps access scoped to each project automatically.

Server	Complements Filesystem By…
GitHub MCP	Push local changes to remote
Git MCP	Version control operations
Memory MCP	Remember project context
PostgreSQL MCP	Query data, export to files

Summary

The Filesystem MCP Server enables powerful local file access:

✅ Sandboxed security with explicit directory grants
✅ Full file operations: read, write, search, move
✅ Read-only mode for maximum safety
✅ Universal support - Works with Claude, ChatGPT, Copilot, Gemini
✅ Linux Foundation - Part of Agentic AI Foundation (Dec 2025)

Best use cases:

Code review with full codebase context
Documentation generation from source
Project scaffolding and setup
Note searching and organization
Data file analysis

Security checklist:

☐ Only grant specific directories you need
☐ Never grant home directory
☐ Avoid credential/config folders
☐ Use read-only mode when possible
☐ Review paths before adding

Next: Learn about PostgreSQL MCP Server → for database access.

Questions about Filesystem MCP? Check the source code on GitHub or join the MCP Discord.

TL;DR - Filesystem MCP Quick Start

Why Filesystem MCP Matters

Use Cases

Security Model Explained

The Sandbox

Key Security Features

What AI CAN’T Do

Installation & Configuration

Prerequisites

Claude Desktop Setup

Multiple Directories

Cursor Setup

Read-Only Mode

Windows Paths

Verify Installation

Available Tools

Read Operations

Write Operations

Search Operations

Configuration Best Practices

✅ Do’s

❌ Don’ts

Safe Directory Examples

Practical Workflows

Workflow 1: Code Review

debounce(fn, delay)

Example Prompts

Reading Files

Writing Files

File Organization

Analysis Prompts

Troubleshooting

Issue: “Path not allowed”

Issue: “File not found”

Issue: “Permission denied”

Issue: “Read-only mode prevents writes”

Combining with Other MCPs

Filesystem + GitHub

Filesystem + Memory

Filesystem + Playwright

Advanced: Multiple Configs

Separate Work and Personal

Project-Specific Access

Related MCP Servers

Summary