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

Related MCP server: Filesystem MCP Server SSE

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 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:

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.