Filesystem MCP server

The Filesystem MCP Server provides a Node.js implementation of the Model Context Protocol for filesystem operations, allowing you to perform various actions like reading, writing, and manipulating files and directories through a standardized interface.

Installation Options

Using with Claude Desktop

Add the MCP server configuration to your claude_desktop_config.json file using one of the following methods:

Docker Installation

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

Note: All directories must be mounted to /projects by default. You can provide sandboxed directories by mounting them with specific paths, and add the ro flag to make a directory read-only.

NPX Installation

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Using with VS Code

For manual installation in VS Code, add the following to your User Settings (JSON) file:

Docker Configuration for VS Code

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
          "mcp/filesystem",
          "/projects"
        ]
      }
    }
  }
}

NPX Configuration for VS Code

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "${workspaceFolder}"
        ]
      }
    }
  }
}

Alternatively, you can add these configurations to .vscode/mcp.json in your workspace (without the mcp key).

Available Tools and Usage

File Operations

Reading Files

To read the contents of a file:

• Tool: read_file
• Input: path (string)
• Reads complete file contents with UTF-8 encoding

To read multiple files at once:

• Tool: read_multiple_files
• Input: paths (string[])
• Failed reads won't stop the entire operation

Writing and Editing Files

To create a new file or overwrite an existing one:

• Tool: write_file
• Inputs:
  • path (string): File location
  • content (string): File content

To make selective edits to a file:

• Tool: edit_file
• Inputs:
  • path (string): File to edit
  • edits (array): List of edit operations
    • oldText (string): Text to search for
    • newText (string): Text to replace with
  • dryRun (boolean): Preview changes without applying (default: false)

Directory Operations

To create a new directory:

• Tool: create_directory
• Input: path (string)
• Creates parent directories if needed

To list directory contents:

• Tool: list_directory
• Input: path (string)
• Returns contents with [FILE] or [DIR] prefixes

To move or rename files and directories:

• Tool: move_file
• Inputs:
  • source (string)
  • destination (string)

Search and Information

To search for files and directories:

• Tool: search_files
• Inputs:
  • path (string): Starting directory
  • pattern (string): Search pattern
  • excludePatterns (string[]): Patterns to exclude

To get file or directory metadata:

• Tool: get_file_info
• Input: path (string)
• Returns size, timestamps, type, and permissions

To list allowed directories:

• Tool: list_allowed_directories
• No input required
• Returns directories the server can access

Security Note

The server will only allow operations within directories explicitly specified via the args parameter in your configuration. Always use the dryRun option first when using the edit_file tool to preview changes before applying them.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.