Skip to content

mcp/filesystem terminates unexpectedly #2505

Closed as not planned
Closed as not planned
mcp/filesystem terminates unexpectedly#2505
Labels
bugSomething isn't workingclosed-superseded-v2Closed: fixed or made obsolete by the v2 / 2026-07-28 refactor (#4875)server-filesystemReference implementation for the Filesystem MCP server - src/filesystem

Description

@chrissound
chrissound
opened on Aug 7, 2025

The process terminates unexpectedly? I'm trying to run this standalone, I'll use the API directly.

root@mcp-test:~/servers# docker run --rm -v $PWD:/projects mcp/filesystem /projects
Secure MCP Filesystem Server running on stdio
root@mcp-test:~/servers# echo $?
0

To Reproduce

git clone git@github.com:modelcontextprotocol/servers.git
cd servers
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
root@mcp-test:~/servers# docker run --rm -v $PWD:/projects mcp/filesystem /projects
Secure MCP Filesystem Server running on stdio

I expect it to instead be continually running.

Activity

  1. chrissound
    added
    bugSomething isn't working
    on Aug 7, 2025

  2. chrissound commented on Aug 8, 2025

    @chrissound
    chrissound
    on Aug 8, 2025
    Author

    I had to run docker run -i (interactively), and then paste {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} and press enter (push it to stdin of the process)... After which it sends the response to stdout:

    root@mcp-test:~/servers# docker run -i --rm -v $PWD:/projects mcp/filesystem /projects
Secure MCP Filesystem Server running on stdio
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
{"result":{"tools":[{"name":"read_file","description":"Read t
...

    The next mission (not that anyone cares...) is to figure out how to run this remotely as a proper MCP server.

  3. olaservo
    added
    server-filesystemReference implementation for the Filesystem MCP server - src/filesystem
    on Aug 24, 2025

  4. olaservo commented on Aug 24, 2025

    @olaservo
    olaservo
    on Aug 24, 2025
    Member

    @claude could you help us understand why Chris is having these issues?

  5. claude commented on Aug 24, 2025

    @claude
    claudeBot
    on Aug 24, 2025 – with Claude
    Contributor

    Claude finished @olaservo's task —— View job

    Analysis: MCP Filesystem Server Termination Issue

    Root Cause Analysis

    The MCP Filesystem server is working as designed - it's not terminating unexpectedly. Here's what's actually happening:

    Technical Explanation

    Todo List:

    • Read the filesystem server source code
    • Examine the Dockerfile and entry point
    • Analyze the server's main loop and stdin handling
    • Check how MCP servers are designed to work
    • Provide explanation of the behavior
    • Suggest potential improvements

    How MCP Servers Work

    MCP (Model Context Protocol) servers are designed to run as stdio-based JSON-RPC servers, not as traditional daemons. They:

    1. Listen on stdin/stdout for JSON-RPC messages
    2. Block waiting for input from the client
    3. Exit when stdin closes (when no client is connected)

    The Code Flow

    In src/filesystem/index.ts:693-705:

    async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Secure MCP Filesystem Server running on stdio");
  // ... server now waits for stdin input
}

    The StdioServerTransport creates an event-driven server that:

    • Reads JSON-RPC requests from stdin
    • Writes JSON-RPC responses to stdout
    • Logs messages to stderr
    • Exits when stdin is closed/EOF

    Why Chris's Commands Behave This Way

    1. Without -i flag:

      docker run --rm -v $PWD:/projects mcp/filesystem /projects
      • Docker doesn't attach to stdin (no TTY)
      • Server starts, prints message to stderr, stdin immediately gets EOF
      • Server exits cleanly with code 0

    2. With -i flag:

      docker run -i --rm -v $PWD:/projects mcp/filesystem /projects
      • Docker keeps stdin open and attached
      • Server waits for JSON-RPC messages
      • When Chris sends {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}, it responds
      • Server continues running until stdin closes

    This is Normal MCP Behavior

    All MCP servers in the repository follow this same pattern:

    • src/memory/index.ts:413
    • src/sequentialthinking/index.ts:277
    • src/everything/stdio.ts:9

    They're designed to be used by MCP clients (like Claude Desktop, IDEs, etc.) that manage the stdio connection, not run standalone as services.

    Solution for Standalone Usage

    If you want to run this as a remote server, you have a few options:

    1. Use stdin piping: echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | docker run -i --rm -v $PWD:/projects mcp/filesystem /projects

    2. Create a wrapper that maintains stdin connection

    3. Use HTTP transport (would require code modifications)

    This isn't a bug - it's the intended stdio-based architecture of MCP servers.

  6. chrissound commented on Aug 24, 2025

    @chrissound
    chrissound
    on Aug 24, 2025
    Author

    Documentation is not comprehensive or concise. The fact that the 'main component' is using stdin/stdout is completely an internal detail - maybe it makes it easier to 'integrate' with claude desktop etc, but it seems completely irrelevant to the MCP protocol. Hence the confusion.

  7. olaservo commented on Aug 27, 2025

    @olaservo
    olaservo
    on Aug 27, 2025
    Member

    Thanks @chrissound - one thing I was not clear on in your other comment was the statement "figure out how to run this remotely" - filesystem is meant to be run as a local server (which is why it only uses STDIO transport). So I'm not sure on what exactly you are trying to implement remotely - do you just mean run it on a deployed docker container?

  8. chrissound commented on Aug 27, 2025

    @chrissound
    chrissound
    on Aug 27, 2025
    Author

    I was trying to call the anthropic API directly (without claude code, or claude desktop). And I was investigating how to setup my own MCP server, hence it can only run 'remotely' as that is how anthropic's api interacts with MCP servers - via HTTP.

    In other words I thought something like this:

    1. Setup a 'mcp server' that is publicly accessible
    2. Call the anthropic api specifying the publicly accessible mcp server, and asking it to use the mcp server to list files
    3. I see the response from anthropic api showing the ls results.

  9. cliffhall commented on Oct 19, 2026

    @cliffhall
    cliffhall
    on Oct 19, 2026
    Member

    Closing: superseded by the v2 release.

    Thank you for reporting this, and apologies for the long wait for a response.

    Since this was filed, the reference servers have been rebuilt for the 2026-07-28 MCP specification (#4857) and released as v2 (2.0.0 on npm for the TypeScript servers, 2026.10.19 on PyPI for the Python servers). Each server now runs on v2 of its SDK, and the behavior described here has either been fixed or no longer exists in the same form. The filesystem server is a stdio server and exits when stdin closes, so it must be run with docker run -i by an MCP client; this is expected behavior, not a defect.

    This is not a judgment on whether the problem was real; it's a consequence of the code it describes having been replaced. This is happening as part of the backlog triage in #4875.

    If this still happens on the v2 release, we'd genuinely like to know. Please open a fresh issue with the version you're running and steps to reproduce, and we'll look at it. Note that this repository accepts contributions as issues rather than pull requests; see CONTRIBUTING.md.

    Thanks for taking the time to report it.

  10. cliffhall
    closed this as not plannedon Oct 19, 2026
  11. cliffhall
    added
    closed-superseded-v2Closed: fixed or made obsolete by the v2 / 2026-07-28 refactor (#4875)
    on Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingclosed-superseded-v2Closed: fixed or made obsolete by the v2 / 2026-07-28 refactor (#4875)server-filesystemReference implementation for the Filesystem MCP server - src/filesystem

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions