Filesystem MCP Server Configuration Guide

Filesystem MCP Server Configuration Guide

The official Filesystem Model Context Protocol (MCP) server provides AI hosts with controlled read, write, and directory inspection access to explicitly designated local storage directories. For developers using Claude Desktop, Cursor, and OpenAI Codex CLI, scoped filesystem access serves as the baseline primitive for codebase refactoring, log analysis, and automated project builds.

Granting LLM agents direct file access requires strict isolation. Without rigorous sandbox boundaries, an agent can follow symlinks outside target folders, expose credentials (.env, ~/.ssh/id_rsa), or corrupt host filesystems. The official server enforces boundary restrictions directly at the protocol layer.

The sections below walk through the sandboxed execution model, host configuration JSON/TOML, tool calling semantics, and production error mitigation.

1. System Architecture and Sandboxed Execution

The Filesystem MCP server executes as a dedicated child process communicating with the AI host over Standard Input and Output (stdio). At startup, the server receives a list of authorized directory paths via its command-line arguments. These paths form a closed sandbox boundary.

Core Security Invariants

1. ▸Explicit Directory Boundaries: The server only permits operations inside the exact directories passed to its command-line arguments. If an authorized path is /home/user/workspace, any request targeting /home/user/documents is immediately rejected.
2. ▸Canonical Realpath Resolution: To prevent symlink escapes and directory traversal attacks (such as ../../etc/passwd), the server resolves symlinks using fs.realpathSync() and verifies that the canonical target resides within an allowed root.
3. ▸Pure Data IO: The filesystem server provides file reading, editing, and listing tools. It possesses no shell execution capabilities, preventing command injection vulnerabilities.

2. Environment Prerequisites and Software Matrix

Verify that your workstation satisfies the following software requirements:

Create a designated sandbox directory for development:

# macOS / Linux
mkdir -p ~/projects/mcp-sandbox

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$HOME\projects\mcp-sandbox"

3. Multi-Host Configuration Snippets

Configure your AI clients to launch the Filesystem server over stdio. Provide absolute paths to your allowed directories.

Claude Desktop Configuration (claude_desktop_config.json)

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

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

[!IMPORTANT] On Windows, format paths using forward slashes (e.g. C:/Users/developer/projects/mcp-sandbox) or double backslashes (C:\\Users\\developer\\projects\\mcp-sandbox). Single backslashes act as escape characters in JSON and will invalidate the file.

Cursor IDE Configuration (.cursor/mcp.json)

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

OpenAI Codex CLI Configuration (~/.codex/config.toml)

[mcp_servers.filesystem]
command = "npx"
args = [
  "-y",
  "@modelcontextprotocol/server-filesystem",
  "/home/developer/projects/mcp-sandbox"
]

4. Exposed Tools and Capability Reference

The Filesystem MCP server exposes an extensive suite of granular file management tools:

5. JSON-RPC 2.0 Wire Payloads

Inspecting the underlying protocol framing helps diagnose communication issues between host and server.

Tool Invocation: Reading a File (tools/call)

{
  "jsonrpc": "2.0",
  "id": "fs-read-101",
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/home/developer/projects/mcp-sandbox/package.json"
    }
  }
}

Formatted Response Payload

{
  "jsonrpc": "2.0",
  "id": "fs-read-101",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"name\": \"mcp-sandbox\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\"\n}"
      }
    ]
  }
}

Tool Error Response (Sandbox Violation)

When an agent attempts to read an unauthorized path:

{
  "jsonrpc": "2.0",
  "id": "fs-read-102",
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Access denied: Path '/etc/passwd' is outside of allowed directories."
      }
    ]
  }
}

6. Common Errors and Production Troubleshooting

When operating the filesystem server across various development workflows, watch for the following operational errors:

Error: Access denied - path outside allowed directories

• ▸Root Cause: The requested file path is not within the directories specified in the client configuration args.
• ▸Resolution: Verify that the path provided in the prompt matches the absolute path declared in your config. Remember that relative paths (./) resolve relative to the server working directory, not your current shell directory.

Error: File Truncation on Large Rewrites (write_file)

• ▸Root Cause: When an AI agent attempts to rewrite a 1,500-line source file using write_file, output token generation limits may cause the response to cut off mid-file, corrupting the code.
• ▸Resolution: Prompt the agent to use edit_file for targeted line substitutions, or chunk modifications across separate helper modules.

Error: spawn npx ENOENT on Windows or Non-Login Shells

• ▸Root Cause: The host application could not find npx in the system environment PATH.
• ▸Resolution: Provide the absolute binary path in command:
  • ▸Windows: C:\\Program Files\\nodejs\\npx.cmd
  • ▸macOS / Linux: /usr/local/bin/npx or /opt/homebrew/bin/npx

7. External Citations and Security Guardrails

Adhere to these operational security best practices when granting filesystem permissions:

• ▸Principle of Least Privilege: Never expose your user home directory (/Users/username or /home/user) or filesystem root (/ or C:/). Always configure narrow project-specific directories.
• ▸Exclude Secret Files: Ensure directories exposed to the agent do not contain unprotected private keys, API secrets, or database backup dumps.
• ▸Official Specifications and Repositories:
  • ▸Official Filesystem MCP Server GitHub Repository (opens in a new tab)
  • ▸Official Filesystem MCP Package on npm (opens in a new tab)
  • ▸Model Context Protocol Specification (opens in a new tab)