Filesystem MCP server

The MCP Filesystem Server implements the Model Context Protocol for filesystem operations with comprehensive permission controls. It provides a secure way to perform file and directory operations with granular permissions, allowing AI assistants and other applications to interact with the filesystem in a controlled manner.

Installation Options

Using NPX (Recommended)

The simplest way to use the server is with npx:

npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Using Docker

You can also run the server in a Docker container:

docker run -i --rm \
  --mount type=bind,src=/Users/username/Desktop,dst=/projects/Desktop \
  mcp/filesystem \
  /projects

Configuration

Basic Configuration

The server requires at least one directory path to operate on, and by default runs in read-only mode:

npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Permission Flags

Control what operations the server can perform:

• --readonly: Enforces read-only mode (default if no permissions specified)
• --full-access: Enables all operations (create, edit, move, delete)
• Individual permissions:
  • --allow-create: Allow creation of files and directories
  • --allow-edit: Allow modification of existing files
  • --allow-move: Allow moving/renaming files and directories
  • --allow-delete: Allow deletion of files and directories

Symlink Handling

• By default, symlinks are followed (both link and target must be in allowed directories)
• Use --no-follow-symlinks to disable symlink following

Integration with AI Tools

Cursor Configuration

Create or modify .cursor/mcp.json in your project:

{
  "mcpServers": {
    "my-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--full-access",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Claude Desktop Configuration

Modify claude_desktop_config.json:

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

Multiple Directories with Different Permissions

If you need different permission levels for different directories, create multiple server configurations:

{
  "mcpServers": {
    "readonly-filesystem": {
      "command": "npx",
      "args": [
        "-y", 
        "@modelcontextprotocol/server-filesystem",
        "--readonly",
        "~/sensitive/directory"
      ]
    },
    "writeable-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--full-access",
        "~/sandbox/directory"
      ]
    }
  }
}

Available Operations

File Operations

• read_file: Read complete contents of a file
• read_multiple_files: Read multiple files simultaneously
• create_file: Create a new file with content
• modify_file: Replace content of an existing file
• edit_file: Make selective edits using pattern matching
• delete_file: Delete a file

Directory Operations

• create_directory: Create new directory or ensure it exists
• list_directory: List directory contents
• directory_tree: Get recursive tree view of directory structure
• move_file: Move or rename files and directories
• delete_directory: Delete a directory
• search_files: Recursively search for files/directories
• find_files_by_extension: Find all files with specific extension

Utility Operations

• get_file_info: Get detailed file/directory metadata
• get_permissions: Get current server permissions
• list_allowed_directories: List all accessible directories
• xml_to_json: Convert XML file to JSON format
• xml_to_json_string: Convert XML file to JSON string
• xml_query: Query XML file using XPath expressions
• xml_structure: Analyze XML structure without reading entire file

Command Line Examples

1. Read-only access:

npx -y @modelcontextprotocol/server-filesystem --readonly /path/to/dir

2. Full access:

npx -y @modelcontextprotocol/server-filesystem --full-access /path/to/dir

3. Specific permissions:

npx -y @modelcontextprotocol/server-filesystem --allow-create --allow-edit /path/to/dir

4. No symlink following:

npx -y @modelcontextprotocol/server-filesystem --full-access --no-follow-symlinks /path/to/dir

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.