Filesystem MCP server

Secure sandboxed file reading, directory listing, file writes, and directory traversal.

Local (stdio)Credential

Set up Filesystem

Configuration examples, not tested connections. Replace placeholders and review the upstream documentation before use.

Claude Code

Run in your terminal.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "/REPLACE_WITH_ALLOWED_DIRECTORY"

Cursor

Merge into ~/.cursor/mcp.json

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

Codex

Run in your terminal.

codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "/REPLACE_WITH_ALLOWED_DIRECTORY"

Gemini CLI

Merge into ~/.gemini/settings.json

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

OpenCode

Merge into ~/.config/opencode/opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/REPLACE_WITH_ALLOWED_DIRECTORY"
      ],
      "enabled": true
    }
  }
}

VS Code

Merge into .vscode/mcp.json

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/REPLACE_WITH_ALLOWED_DIRECTORY"
      ]
    }
  }
}

Using more than one server?Add to a config with other servers

Step-by-step setup guides: Claude Code and Codex CLI, Cursor and VS Code. In Claude Desktop, the Cursor JSON goes in claude_desktop_config.json. This is a local server that runs on your machine; see remote vs local servers and authentication and security basics.

Overview

Filesystem is one of the actively maintained reference servers in the Model Context Protocol servers repository, published on npm as @modelcontextprotocol/server-filesystem. It runs locally as a Node.js process over stdio and lets an agent work with files on your machine, but only inside the directories you allow.

Its tools cover everyday file work: read_text_file, read_media_file and read_multiple_files; write_file and edit_file, which applies line-based edits, returns a git-style diff and supports a dry run; create_directory, list_directory, directory_tree and move_file; plus search_files, get_file_info and list_allowed_directories. Use it when a chat or IDE client has no built-in file access, or when you want to give an agent a deliberately narrow view of a project or notes folder.

Setup caveats: access control is the point of this server. You either pass allowed directories as command-line arguments (the snippets below use a placeholder you must replace) or let a client that supports MCP Roots supply them, in which case the client's roots replace the command-line list. If neither is provided, the server exits at startup. Every operation is checked against the allowed directories. write_file overwrites existing files without asking, and upstream notes the write is not crash-atomic, so start with a copy or a version-controlled folder. The server labels its tools with MCP tool annotations so clients can tell read-only tools from write-capable ones.

Example tools

  • read_text_file
  • write_file
  • list_directory
  • move_file

Tool names are upstream examples. The server's live tool list can differ.

Browse Developer Tools servers

Sources

This page was written from the upstream documentation below and last reviewed on 11 October 2026. Listing is not a security or compatibility endorsement. Report a correction through the contact page.