MCP Directory

How to add Filesystem (Reference) to Windsurf

Official MCP reference server for secure local filesystem read/write within allowed directories. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 74k★ · stdio · no auth · official

Windsurf config for Filesystem (Reference)

npx -y @modelcontextprotocol/server-filesystem /absolute/path/to/dir
{
  "mcpServers": {
    "filesystem-reference": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/absolute/path/to/dir"
      ]
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Filesystem (Reference) config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Filesystem (Reference)'s tools become available to Cascade.

Before you start

  • Node.js 18+ (to run via `npx @modelcontextprotocol/server-filesystem`), OR Docker if using the container image
  • No credentials or auth — access is granted by listing allowed directories as args, or via the client's MCP Roots support
  • One or more directory paths you intend to expose to the model

What Filesystem (Reference) can do in Windsurf

read_text_file

Read a file's contents as UTF-8 text (supports head/tail line limits).

read_media_file

Read an image or audio file and return it as base64.

read_multiple_files

Read several files at once in a single call.

write_file

Create a new file or overwrite an existing one.

edit_file

Make selective line-based edits using pattern matching, returning a git-style diff.

create_directory

Create a directory, including any missing parent directories.

list_directory

List directory contents with [FILE]/[DIR] type prefixes.

list_directory_with_sizes

List directory contents including each entry's size.

Security

Only the directories passed as arguments are accessible, but any granted directory is fully readable and writable; scope it to a project folder rather than your home directory. Never grant root or system paths.

Filesystem (Reference) + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Filesystem (Reference) config there under the "mcpServers" key and restart the client.

Is Filesystem (Reference) safe to use with Windsurf?

Only the directories passed as arguments are accessible, but any granted directory is fully readable and writable; scope it to a project folder rather than your home directory. Never grant root or system paths.

How do I restrict which folders the model can touch?

Pass each allowed directory as a command-line argument when launching the server, or have your client supply them via MCP Roots. Any path outside that set is rejected.

Does it require an API key or login?

No. It runs locally over stdio with no authentication. Security comes entirely from the allowed-directory sandbox.

Can I make a directory read-only?

Yes, most easily with the Docker image by appending `,ro` to the bind mount (e.g. `/host/path,dst=/projects/foo,ro`).

View repo Full Filesystem (Reference) page