modelcontextprotocol / modelcontextprotocol/servers
Filesystem MCP writes hang when launched via `npx -y`; reliability improves with pinned global install
Nobody has claimed this yet.
- 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:
- Configure Filesystem MCP in claude_desktop_config.json using
command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", <dirs>] - Restart Claude Desktop
- Call read operations: succeed (list_directory, search_files)
- Call write operation (edit_file): intermittently hangs for 4 minutes, then times out with "unresponsive"
- Subsequent calls also hang
Fix that worked:
- Install globally:
npm install -g @modelcontextprotocol/server-filesystem - Update config
commandto the direct binary path, removenpxand-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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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