Filesystem MCP Server

Reviewed 2026-10-13productivityMCP Server# mcp # filesystem # files # reference-server # nodejs

Official MCP reference server for reading, writing, editing, moving and searching files inside directories you allow.

Security Reviewed

Local-only file server confined to the directories you allow, with symlink checks and no network code; it can overwrite and move files inside them.

Install Filesystem MCP Server in Google Antigravity

Antigravity reads MCP servers from ~/.gemini/config/mcp_config.json (all projects) or .agents/mcp_config.json (one project) (official docs).

EasiestOption 1: paste this to your Antigravity agent

Install the "Filesystem MCP Server" MCP server for Google Antigravity.
Follow the steps at https://www.antigravityskills.org/install/filesystem-mcp-server.md (source: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem).
Before running anything, show me what you will download and whether it includes scripts, and wait for my OK.
Ask me for any keys or paths it needs. When done, check that it is listed under Installed MCP Servers.

The agent reads the install file, shows you what it will download and waits for your OK.

Option 2: install it yourself

1. Make sure Node.js is installed
```
node --version
```
The server runs through npx, which comes with Node.js. Docker also works (see the README).
2. Open the Antigravity MCP config
Global: ~/.gemini/config/mcp_config.json. This project only: .agents/mcp_config.json. In Antigravity 2.0 you can also use Settings > Customizations > Add MCP.
3. Add the server under mcpServers
```
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/project"
      ]
    }
  }
}
```
Same command and args the README documents for Claude Desktop, with your own folder in place of /path/to/your/project. List only the folders the agent really needs; add more paths as extra args.
4. Check that it loaded
Open Settings > Customizations > Installed MCP Servers; filesystem should be listed and switched on. Then ask the agent to call list_allowed_directories.

MCP servers are not skills: they do not go in .agents/skills/. The Filesystem server's README does not mention Antigravity; this config uses its documented stdio command in Antigravity's mcpServers format.

Using Claude Code, Cursor or Codex? See other assistants below.

What is Filesystem MCP Server?

The Filesystem MCP Server is the official MCP reference server that lets an agent read, write, edit, move and search files, but only inside the directories you list when you start it. It is a Node.js (TypeScript) package, @modelcontextprotocol/server-filesystem, in the modelcontextprotocol/servers repository, and it talks over stdio. What we counted in src/filesystem at commit bbb701e (2026-10-11, version 1.0.0): 14 registered tools (13 in the README plus a deprecated read_file alias), 10 of them read-only and 4 able to change files (create_directory, write_file, edit_file, move_file), 3 of which are marked destructive; 7 source files totalling 2,085 lines; 11 test files; and 5 runtime dependencies (the MCP SDK, diff, glob, minimatch, zod).

How to use Filesystem MCP Server?

Add the server to your MCP client's config with npx (or Docker) and give it one or more directories. The agent then calls tools such as read_text_file, edit_file (with dryRun to preview a diff) or search_files, and list_allowed_directories shows what it can reach. Clients that support MCP Roots can replace the directory list at runtime; with Roots, the client's roots completely replace the command-line directories (README).

Key features of Filesystem MCP Server

✓14 tools: read_file (deprecated), read_text_file, read_media_file, read_multiple_files, write_file, edit_file, create_directory, list_directory, list_directory_with_sizes, directory_tree, move_file, search_files, get_file_info, list_allowed_directories (we counted in server.ts)
✓edit_file accepts several edits at once, keeps CRLF or LF line endings, and has a dryRun mode that returns a git-style diff without writing (README says)
✓Access limited to allowed directories, from arguments or MCP Roots; a roots update with no valid root revokes access until the client sends one again (README says)
✓Symlinks are resolved with realpath and rejected when they point outside the allowed directories; overwrites refuse symlinks via an O_NOFOLLOW open on POSIX (we read lib.ts)
✓Every tool sets openWorldHint false, and the source imports no network or child-process modules (we counted the imports)
✓Docker option: mount folders under /projects and add ro to a mount to make it read-only (README says)

When to use Filesystem MCP Server

1Let an agent summarise or search a folder of notes without giving it your whole disk
2Edit config or source files with a previewed diff before applying
3Give a read-only view of a project by mounting it with ro in Docker
4Move or rename batches of files inside one working folder

Installation & Setup Guide

MCP Server Integration

Follow these steps (taken from the project's own docs) to configure Filesystem MCP Server in your development environment.

Step 1: Claude Desktop (NPX), from the READMEclaude

{"mcpServers": {"filesystem": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/path/to/other/allowed/dir"]}}}

Add to claude_desktop_config.json. On Windows the README uses "command": "cmd" with "/c", "npx" at the start of args.

Step 2: Claude Desktop (Docker), from the READMEclaude

{"mcpServers": {"filesystem": {"command": "docker", "args": ["run", "-i", "--rm", "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop", "mcp/filesystem", "/projects"]}}}

Mount directories under /projects; add ,ro to a mount to make it read-only.

Step 3: VS Code, from the READMEvscode

{"servers": {"filesystem": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]}}}

Add to your user mcp.json (MCP: Open User Configuration) or .vscode/mcp.json.

Step 4: Claude Code: not documented by the projectclaude

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/your/project

The server's README does not cover Claude Code. This uses the general claude mcp add syntax from the Claude Code docs (code.claude.com/docs/en/mcp) with the README's command.

Step 5: Cursor: not documented by the projectcursor

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

Not covered by the server's README. Cursor's docs (cursor.com/docs/context/mcp) read .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) with this mcpServers shape.

Usage Example & Verification

Prompt / Request Example

1. (our example)
Use list_allowed_directories, then list the files in my project folder and show the first 20 lines of README.md.

2. (our example)
In config.yaml change the port from 3000 to 8080. Do a dryRun first and show me the diff before applying it.

3. (our example)
Search my project for files matching *.test.ts, excluding node_modules, and give me the full paths.

Expected Output / Response

1. The agent calls list_allowed_directories, list_directory and read_text_file with head set to 20. Anything outside the allowed folders is refused with an 'Access denied' error. 2. edit_file with dryRun true returns a git-style diff and writes nothing; after you approve, the same call without dryRun changes the file (README says). 3. search_files does a recursive glob-style search with excludePatterns and returns full paths. These behaviours come from the README's tool list; we read the code and did not run the server.

Installation Confirmation Method

Open Settings > Customizations > Installed MCP Servers in Antigravity 2.0 and confirm filesystem is listed and on, then ask the agent to call list_allowed_directories; it should print exactly the folders you passed.

Security Review

Static review

Reviewed Date

2026-10-13

Audited Ref / Commit

bbb701e7ac1e57f3edd1c2836b94c5457eaf7b9c

Reviewer

antigravityskills.org (static code review)

Local-only file server confined to the directories you allow, with symlink checks and no network code; it can overwrite and move files inside them.

Full review: scope, findings, risks

Audit Scope:src/filesystem at commit bbb701e (2026-10-11, 1.0.0): README.md, package.json, CHANGELOG.md, Dockerfile, index.ts, server.ts, lib.ts, path-utils.ts, path-validation.ts, roots-utils.ts, version.ts, and the repository LICENSE. Imports and process, network and environment access were grepped across all source files; test files were listed, not read. Static review only; the server was not run.

Key Findings:No network, child-process, eval or environment-variable access in the 7 source files; imports are fs, path, os, url, stream, string_decoder, diff, minimatch, zod and the MCP SDK. It writes and moves files inside allowed directories: new files are created with the exclusive wx flag, existing files are overwritten in place after an lstat plus O_NOFOLLOW check, and move_file refuses an existing destination. No API keys.

Identified Operational Risks & Permissions:Destructive write, edit and move inside allowed directories; a broad allowed directory such as a home folder exposes everything in it. Overwrites are not crash-atomic. Roots from the client replace your command-line directories, so a client that sends broad roots widens access.

We re-read src/filesystem at commit bbb701e, which is newer than our previous review (5abed86): the server now lives in server.ts as a createServer() factory and 1.0.0 changed overwrites to in-place writes. The 7 TypeScript sources import only Node built-ins (fs, path, os, url, stream, string_decoder), diff, minimatch, zod and the MCP SDK; a grep found no fetch, http, net, child_process, spawn, exec, eval or process.env. Path checks live in lib.ts: allowed directories are realpath-resolved at startup, each request path is resolved and rejected if outside, and a symlink whose target is outside is refused (Access denied - symlink target outside allowed directories). writeFileContent creates new files with the exclusive wx flag and falls back to overwriteInPlace, which lstat-checks the file, opens it with O_NOFOLLOW (POSIX) and verifies the same device and inode before truncating. moveFile lstat-checks the destination and refuses to overwrite. The 14 tools all set openWorldHint false; 4 are not read-only and 3 are marked destructive. The Dockerfile builds on node:22.12-alpine and installs with npm ci --ignore-scripts. License: the README says MIT; the repository LICENSE says the project is moving to Apache-2.0 for new contributions.

Operational Notes & Known Limitations

Known Limitations

•Only works inside allowed directories. With no directory arguments and a client that does not support Roots, it logs the reason and exits with status 1 (README)
•Needs Node.js (npx) or Docker. The package has 5 runtime dependencies that npx downloads on first run
•write_file overwrites an existing file in place and, since 1.0.0, that is not crash-atomic: a crash mid-write can leave a partly written file (README). Older write-ups, including our previous review of commit 5abed86, described temp-file renames; that changed
•move_file fails if the destination exists; read_text_file always treats files as UTF-8 text
•The README feature list says 'Create/list/delete directories' but there is no delete tool among the 14 (we counted); deleting files is not possible through this server
•We found no file-size cap in server.ts or lib.ts, so a very large read is limited only by the client
•Antigravity: the README documents Claude Desktop and VS Code only and does not mention Antigravity. The Antigravity config below is our adaptation of the documented command
•Difference from the sqlite-mcp-server page on this site: that server is archived and unmaintained, while this one is still under active development (its git history shows roots fixes committed on 2026-10-10)

Frequently Asked Questions

Is the Filesystem MCP Server safe?

It is local-only: the source imports no network or child-process modules, reads no API keys, and refuses paths outside the allowed directories, including symlinks that point outside. But write_file, edit_file and move_file can overwrite or move anything inside those folders, so grant only what you need or use a Docker mount with ro.

How do I install the Filesystem MCP Server in Antigravity?

Add the npx command from the README to Antigravity's mcp_config.json (global ~/.gemini/config/mcp_config.json, or .agents/mcp_config.json for one project) with your folders as extra args, then check Installed MCP Servers. The README itself does not mention Antigravity.

How do I limit which folders it can reach?

Pass them as arguments, or use a client that supports MCP Roots; roots from the client replace the argument list. list_allowed_directories shows the current set.

Can it delete files?

Not directly: among its 14 tools there is no delete tool (we counted), although move_file and write_file can still overwrite data, and the README feature list wording about deleting directories is misleading.

Does it need internet or an API key?

No key. npx downloads the package once; after that the server only touches the local filesystem and every tool sets openWorldHint false.

Supported Platforms

claude

View Source on GitHub

Keep exploring this topic

Browse the full Antigravity skills directory for more source-linked skills with install steps and static safety reviews.

More productivity skills #mcp #filesystem #files #reference-server Use cases

Related Skills

📊

SQLite MCP Server

@modelcontextprotocol

Archived MCP reference server for running SQL against a SQLite file, inspecting tables and collecting insights in a memo.

Static reviewwrites filesoffline

mcpsqlite

🚀

mcporter

@openclaw

OpenClaw's one-file mcporter skill: lets an AI agent list, configure, authenticate and call MCP servers from the shell through the mcporter CLI.

Static reviewinstructions onlynetwork accessruns scripts

mcpcli

💻

DeepWiki

Cognition (Devin)

DeepWiki MCP server from Cognition (Devin): a free hosted endpoint with three tools to read and ask questions about public GitHub repositories' generated documentation. No install, no API key.

Static reviewnetwork access

mcpgithub