modelcontextprotocol / modelcontextprotocol/servers

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.

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

Description

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.

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.

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.