MCP Filesystem Server for Windsurf: Setup & Config

What you can do with MCP Filesystem in Windsurf

Scoped local file operations, content search, and directory trees in a Go binary or library.

• Search file names and text within approved directories.
• Generate directory trees and inspect file metadata.

Before you start: MCP Filesystem in Windsurf

• Go for the documented go install method
• Install github.com/mark3labs/mcp-filesystem-server@latest
• Allowed directories supplied at launch

Replace the example allowed paths. The README also documents Docker and embedding the filesystemserver package in Go applications.

MCP Filesystem Windsurf configuration

1. Choose Windsurf configuration scope

   For MCP Filesystem Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add MCP Filesystem Server to Windsurf

   Use the mcp-filesystem-server entry below in mcpServers. Keep MCP Filesystem Server's documented stdio connection fields and your other Windsurf entries.

3. Check MCP Filesystem Server in Windsurf

   MCP Filesystem Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-filesystem-server": {
      "command": "mcp-filesystem-server",
      "args": [
        "/path/to/allowed/directory",
        "/another/allowed/directory"
      ],
      "env": {}
    }
  }
}

MCP Filesystem tools available to Windsurf

MCP Filesystem's stored tool list documents 14 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

read_file

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for read_file.

read_multiple_files

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for read_multiple_files.

write_file

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for write_file.

copy_file

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for copy_file.

move_file

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for move_file.

Move or rename a file or directory.

delete_file

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for delete_file.

Remove a file or directory, optionally recursively.

modify_file

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for modify_file.

Replace matching text using a literal string or regex.

list_directory

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for list_directory.

create_directory

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for create_directory.

tree

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for tree.

search_files

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for search_files.

Find files and directories whose names match a pattern.

search_within_files

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for search_within_files.

Find text inside files across a directory tree.

get_file_info

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for get_file_info.

Inspect metadata for a file or directory.

list_allowed_directories

After refreshing MCP Filesystem in Windsurf settings, check Cascade's tool list for list_allowed_directories.

Report the directories the server may access.

MCP Filesystem: full stored tool descriptions

Troubleshooting MCP Filesystem in Windsurf

• Check mcp-filesystem-server on the machine running Windsurf's MCP integration for MCP Filesystem Server; refresh MCP and inspect Cascade's tools.
• MCP Filesystem Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: The tool set includes overwriting and deletion, not only reads.
• Known limitation: Docker needs a volume mount to modify host files.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions