Filesystem MCP writes hang when launched via `npx -y`; reliability improves with pinned global install

Open Beginner friendly
#4,026 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
65/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
node.js, typescript
Domain
documentation

Research direction

Start with the Filesystem MCP README and its documented npx configuration. Reproduce the listed read and write behavior on macOS with Node.js v22.18.0, then compare it with the global install and direct binary setup. Done means the README’s production install guidance reflects verified behavior and remains clear.

Written by the indexing model from the issue text.

Description

bug

Environment:

  • macOS [your version — Sonoma, Sequoia, whatever]
  • Claude Desktop [Help > About Claude Desktop > version]
  • Node.js v22.18.0
  • Filesystem MCP [version from npm list -g @modelcontextprotocol/server-filesystem]

Reproduction:

  1. Configure Filesystem MCP in claude_desktop_config.json using command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", <dirs>]
  2. Restart Claude Desktop
  3. Call read operations: succeed (list_directory, search_files)
  4. Call write operation (edit_file): intermittently hangs for 4 minutes, then times out with "unresponsive"
  5. Subsequent calls also hang

Fix that worked:

  • Install globally: npm install -g @modelcontextprotocol/server-filesystem
  • Update config command to the direct binary path, remove npx and -y
  • Writes now succeed reliably

Hypothesis:
npx -y may be re-resolving/re-downloading the package on each stdio handshake, introducing a race with Claude Desktop's expected startup window. Pinning the binary path skips npx entirely. This would affect every macOS user following the default install docs.

Suggested docs change:
Recommend npm install -g + direct binary path in the Filesystem MCP README as the production-grade install pattern, rather than the npx -y pattern which appears more fragile.

Dominant language
TypeScript
Stars
90.5k
Forks
11.7k
Avg merge
2d 2h
Merged PRs (30d)
5

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/servers

All issues in modelcontextprotocol/servers

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.