Filesystem MCP Server with Ignore File Support

A Node.js MCP server for filesystem operations with support for custom ignore files (.gitignore, .cursorignore, .cascadeignore, .claudeignore, etc.).

Protect sensitive data by controlling which files AI agents can access using gitignore-style patterns.

Features

• Ignore File Support: Filter files using .gitignore, .cursorignore, .cascadeignore, or any custom ignore file
• Unified File Operations: Single endpoints for reading/writing/editing multiple files
• Automatic Project Detection: Detects Laravel, Python, Node.js, and other project types
• Token Optimization: Smart truncation and compact directory trees for large projects
• MCP Resources: Exposes workspace info and project details as MCP resources
• Dynamic Access Control: Via command-line args or MCP Roots protocol

Installation & Usage

Quick Start with NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@a13-team/filesystem-mcp-ignore",
        "/path/to/your/project"
      ]
    }
  }
}

With Ignore Files

To enable ignore file filtering, use the --ignore-files or -i flag:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@a13-team/filesystem-mcp-ignore",
        "-i", ".gitignore,.cursorignore",
        "/path/to/your/project"
      ]
    }
  }
}

Supported Ignore Files

• .gitignore - Standard Git ignore patterns
• .cursorignore - Cursor AI editor ignore
• .cascadeignore - Windsurf/Cascade ignore
• .claudeignore - Claude AI ignore
• .codeiumignore - Codeium ignore
• Any custom file with gitignore-style patterns

Ignore Pattern Syntax

Patterns follow .gitignore syntax:

# Comments start with #
node_modules/       # Ignore directories
*.log               # Glob patterns
!important.log      # Negation (include)
/root-only.txt      # Root-relative patterns
**/*.test.ts        # Match in any directory

API

Tools (8 unified endpoints)

| Tool | Description | Annotations | |------|-------------|-------------| | read_file | Read single or multiple files (auto-detects text/binary) | readOnly: true | | write_file | Write single or multiple files | destructive: true | | edit_file | Edit single or multiple files with find/replace | destructive: true | | move_file | Move/rename single or multiple files | destructive: false | | create_directory | Create directories (recursive) | idempotent: true | | list_directory | List directory contents with sizes | readOnly: true | | directory_tree | Get JSON tree structure (compact mode) | readOnly: true | | search_files | Search files by glob pattern | readOnly: true |

Tool Details

read_file (Universal Read)

Read one or more files with automatic type detection.

{
  paths: string | string[],  // Single path or array
  encoding?: 'text' | 'base64' | 'auto',  // Default: 'auto'
  head?: number,  // First N lines (text only)
  tail?: number,  // Last N lines (text only)
  maxTokens?: number  // Approx token limit for response size
}

• Text files: Returns content as text (code, config, markdown, etc.)
• SVG files: Returns as text (viewable XML code)
• Binary files: Returns metadata only with message to use native tools
• Large files: Automatically truncated with option to use head/tail

Binary files return metadata shaped like:

{
  "type": "binary_info",
  "path": "/path/to/image.png",
  "mimeType": "image/png",
  "size": 12345,
  "message": "Binary file. Use native tools or download to view."
}

write_file (Universal Write)

Write one or more files.

{
  files: { path: string, content: string } | Array<{ path: string, content: string }>
}

• Creates parent directories automatically
• Overwrites existing files (use with caution)

edit_file (Universal Edit)

Make text replacements in one or more files.

{
  edits: {
    path: string,
    changes: Array<{ oldText: string, newText: string }>
  } | Array<{ path: string, changes: Array<{ oldText: string, newText: string }> }>,
  dryRun?: boolean  // Preview without applying
}

• Returns git-style diff showing changes
• Supports whitespace-flexible matching
• Use dryRun: true to preview changes

move_file (Universal Move)

Move or rename files/directories.

{
  operations: { source: string, destination: string } | Array<{ source: string, destination: string }>
}

list_directory

List directory contents with optional detail formatting.

{
  path: string,
  showSizes?: boolean,  // Default: false
  sortBy?: 'name' | 'size' | 'modified',
  format?: 'compact' | 'detailed' // Default: 'compact'
}

• format: 'detailed' or showSizes: true includes size and mtime summaries.

directory_tree

Get recursive directory structure as JSON.

{
  path: string,
  maxDepth?: number,  // Default: 10
  excludePatterns?: string[],
  compact?: boolean,  // Default: true - collapses large dirs
  omitEmptyDirs?: boolean // Default: false
}

Compact mode automatically:

• Collapses node_modules/, vendor/, .git/, etc.
• Groups many similar files: *.svg (15 files)

MCP Resources

The server exposes these resources:

| URI | Description | |-----|-------------| | workspace://allowed-directories | List of allowed directories | | workspace://project-info | Detected project type and stack | | workspace://tree/{path} | Directory tree JSON for a path |

Project Detection

The server automatically detects project types and exposes info via workspace://project-info resource:

• Laravel/PHP: Detects Livewire, Inertia, Blade, Vue, React, Tailwind, Vite
• Python: Django, Flask, FastAPI with database detection
• Node.js: Next.js, Nuxt, Express, NestJS, React, Vue, Angular, Svelte
• Other: Ruby/Rails, Go, Rust, Java (Maven/Gradle), .NET

Directory Access Control

Directories can be specified:

1. Via command-line arguments (shown above)
2. Via MCP Roots protocol (recommended for dynamic updates)

MCP clients supporting Roots can dynamically update allowed directories at runtime.

Token Optimization

• Response truncation: Large files truncated at ~50k chars with message to use head/tail
• Compact trees: Directory trees collapse node_modules/, vendor/, etc.
• File grouping: Many similar files shown as *.svg (15 files)
• Binary handling: Binary files return metadata only (no base64 bloat)

License

MIT License. See LICENSE.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.