How to Use the Filesystem MCP Server for File Management

Use the Filesystem MCP Server for File Management

The Filesystem MCP server gives AI agents controlled access to your local file system, enabling reading, writing, searching, and managing files. It transforms your agent into an autonomous coding assistant capable of scaffolding projects, refactoring codebases, and organizing your directories.

Installation & Configuration Setup

Add this configuration to your MCP client. You must specify the absolute paths to the directories you want the agent to access.

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

Security Model

The filesystem server implements a strict, non-negotiable security model:

1. ▸Directory Sandboxing: The agent can only access the specific folders passed in the args array.
2. ▸Path Traversal Prevention: Any attempt to read ../../etc/passwd will be blocked.
3. ▸Symlink Resolution: Prevents the agent from escaping the sandbox via symlinks.
4. ▸No Execution: The server cannot execute files or scripts, it can only perform CRUD operations on the file data.

Available Tools

Example Workflows

• ▸Project Scaffolding: "Create a new React project structure inside /projects/demo with components, pages, and utils subdirectories, and generate boilerplate index.js files in each."
• ▸Code Refactoring: "Search for all JavaScript files in /projects/demo/src. Read them and identify any functions that should be extracted into a shared utilities.js file, then perform the extraction."
• ▸File Organization: "Organize the files in my /documents folder by file extension into appropriate subdirectories."

Troubleshooting

• ▸Access Denied: The agent tried to access a path outside of the arguments provided in the configuration. Double-check your config args.
• ▸write_file vs edit_file: If the agent attempts to rewrite a 2,000-line file using write_file, the LLM may truncate the output midway, ruining the file. Always instruct your agent to use edit_file for targeted line replacements in large codebases.

Using with OpenAI Codex

To use this MCP server with the OpenAI Codex CLI, you can add it to your configuration using the codex mcp add command:

codex mcp add --name filesystem --command "npx @modelcontextprotocol/server-filesystem"

(Note: Depending on the server, you may need to append arguments or use --env flags for environment variables as described in the configuration section above)