Filesystem -SSE

Filesystem MCP Server SSE provides a Node.js implementation of the Model Context Protocol (MCP) for interacting with the local filesystem via SSE. It exposes a set of file-system operations (read, write, create/list/delete directories, move, search, and get metadata) through MCP-style tools such as read_file, read_multiple_files, write_file, edit_file, create_directory, list_directory, move_file, search_files, get_file_info, and list_allowed_directories. The server enforces a safety boundary by only allowing operations within directories specified via the server's startup arguments. To use it, start the server and point your MCP client at the server’s SSE endpoint. The example usage in the repository shows a local run by passing a base directory as an argument (for example a project directory) and configuring the MCP client with the appropriate baseUrl. Tools like read_file and write_file accept standard inputs (paths, contents) and will return file contents, metadata, or operation results depending on the tool. There is built-in support for dry-run style previews in edit_file operations, as well as a comprehensive search capability with pattern matching and exclusion. The server is suitable for scripts or automation that need controlled filesystem access with precise capabilities.

Prerequisites:

• Node.js 14+ (or as required by the project)
• npm (comes with Node.js)

Local installation and setup:

1. Clone the repository or download the server source.
2. Install dependencies:

npm install

3. Build if a build step is provided (e.g., TypeScript to JavaScript):

# if a build step exists, e.g., npm run build
npm run build

4. Run the server locally by passing the allowed directory as an argument:

node dist/index.js /path/to/allowed/directory

5. Verify the server starts and is listening on the configured port (e.g., http://127.0.0.1:3001/sse as shown in the examples).

Docker (optional):

1. Build the Docker image (example tag shown in repository):

docker build -t mcp/filesystem -f Dockerfile .

2. Run the container, mounting the allowed project directory into /projects (read-write as permitted):

docker run -i --mount type=bind,src=/path/to/allowed/dir,dst=/projects -p 3001:3001 mcp/filesystem /projects

3. Access the SSE endpoint (e.g., http://localhost:3001/sse) and configure your MCP client accordingly.

Configuring MCP after install:

• Create a configuration snippet that points to the server’s base URL, for example:

{
  "mcpServers": {
    "file_system": {
      "name": "file_system",
      "baseUrl": "http://127.0.0.1:3001/sse"
    }
  }
}

Notes and tips:

• The server restricts all operations to directories provided at startup; never place sensitive paths outside the allowed scope.
• Use edit_file with dryRun: true to preview changes and ensure your edit operations will apply as intended before applying them.
• When using Docker, ensure all directories you want to access are mounted into /projects (or as configured) and respect read/write permissions.
• For large directory trees, use search_files with excludePatterns to improve performance by skipping irrelevant paths.
• Maintain proper error handling in your MCP client to gracefully handle operations that fail (e.g., move_file when destination exists).
• List allowed directories via list_allowed_directories to confirm what the server can access before executing operations.