# How to Use Glob Patterns for File Searching in the MCP Filesystem Server

> Learn to use glob patterns for file searching in the MCP Filesystem server with the search_files tool. Efficiently find files using minimatch recursive matching.

- Repository: [Model Context Protocol/servers](https://github.com/modelcontextprotocol/servers)
- Tags: how-to-guide
- Published: 2026-03-01

---

**The MCP Filesystem server provides a `search_files` tool that accepts glob-style patterns via the `pattern` parameter and uses the `minimatch` library to recursively match files within configured allowed directories.**

The modelcontextprotocol/servers repository includes a reference Filesystem server that exposes secure file operations via the Model Context Protocol (MCP). When you need to locate specific files across directory trees, the `search_files` tool enables powerful recursive searches using standard glob patterns while maintaining strict security boundaries through path validation.

## How Glob Pattern Matching Works in MCP Filesystem

The server implements glob matching through a validated search pipeline defined in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts) and exposed via [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/index.ts).

### Tool Registration and Schema

In [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/index.ts) (lines 632-635), the server registers the `search_files` tool with a JSON schema that requires three key inputs:

- **`path`** — The root directory to search (must be within allowed directories)
- **`pattern`** — The glob-style pattern to match against relative paths
- **`excludePatterns`** — Optional array of glob patterns to exclude from results

The tool description explicitly states that patterns should be "glob-style patterns that match paths relative to the working directory."

### Search Implementation Details

When the tool is invoked, the handler in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/index.ts) (lines 645-648) executes `searchFilesWithValidation`. This function recursively traverses the directory tree and for each entry:

1. Validates the path is within allowed directories using `validatePath` ([`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts), lines 889-891)
2. Checks against `excludePatterns` using `minimatch` (lines 993-996)
3. Matches against the user-supplied `pattern` using `minimatch` (lines 999-1002)

When a pattern matches, the absolute path is added to the result list, which is returned as newline-separated text.

## Supported Glob Pattern Syntax

The `search_files` tool interprets patterns using the **minimatch** library. Patterns are evaluated relative to the `path` argument you supply and must resolve within the server's **allowed directories**.

- `*.ext` — Matches files with the extension `.ext` in the immediate directory (example: `*.md`)
- `**/*.ext` — Recursively matches files with extension `.ext` at any depth (example: `**/*.ts`)
- `folder/**` — Matches everything under `folder/`, including subdirectories (example: `src/**`)
- `!pattern` — Negates a pattern, useful within `excludePatterns` (example: `!node_modules/**`)
- `?.*` — Uses single-character wildcards (example: `?.txt` matches [`a.txt`](https://github.com/modelcontextprotocol/servers/blob/main/a.txt) but not [`ab.txt`](https://github.com/modelcontextprotocol/servers/blob/main/ab.txt))

## Security Validation and Path Restrictions

All file system operations pass through `validatePath` in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts), which:

- Expands home directory shortcuts (`~`)
- Resolves paths against **allowed directories** configured via MCP roots or command-line arguments
- Blocks directory traversal attempts using `..` or symlinks that escape the sandbox

This ensures glob patterns cannot force the server to access files outside its configured boundaries, regardless of how the pattern is constructed.

## Practical Code Examples

### JSON-RPC Request Format

Direct tool invocation via JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "search_files",
  "params": {
    "path": ".",
    "pattern": "**/*.ts",
    "excludePatterns": ["node_modules/**", "dist/**"]
  }
}

```

The response contains matching absolute paths joined by newline characters:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "/home/mcp/project/src/index.ts\n/home/mcp/project/src/lib/util.ts" }
    ]
  }
}

```

### TypeScript SDK Implementation

Using the official TypeScript MCP SDK:

```typescript
import { McpClient } from "@modelcontextprotocol/typescript-sdk";

async function findMarkdownFiles() {
  const client = await McpClient.connectStdIO();
  const result = await client.callTool("search_files", {
    path: ".",
    pattern: "**/*.md",
    excludePatterns: ["node_modules/**"]
  });

  console.log("Matches:\n", result.content[0].text);
}

findMarkdownFiles();

```

### Testing Glob Behavior

The test suite in [`src/filesystem/__tests__/directory-tree.test.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/__tests__/directory-tree.test.ts) demonstrates glob handling:

```typescript
it('should handle glob patterns correctly', async () => {
  const tree = await buildTreeForTesting(testDir, testDir, ['*.env']);
  const fileNames = tree.map(entry => entry.name);
  expect(fileNames).not.toContain('.env');       // *.env excludes .env
  expect(fileNames).toContain('.env.local');    // does NOT exclude .env.local
});

```

This confirms that `*.env` is treated as a glob matching files whose entire name ends with `.env`, excluding files like `.env.local`.

## Key Source Files

- **[`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts)** — Contains `searchFilesWithValidation` and `validatePath` implementations with `minimatch` integration
- **[`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/index.ts)** — Registers the `search_files` tool and connects it to the search logic
- **[`src/filesystem/__tests__/directory-tree.test.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/__tests__/directory-tree.test.ts)** — Unit tests illustrating glob pattern interpretation and exclusion behavior

## Summary

- The `search_files` tool accepts standard glob patterns via the **`pattern`** parameter using the `minimatch` library
- **`excludePatterns`** accepts an array of glob strings to filter results, supporting negation with `!` prefixes
- All candidate paths are validated against **allowed directories** via `validatePath` in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts)
- Patterns are matched relative to the `path` argument, returning absolute paths of all matches
- The implementation prevents directory traversal attacks regardless of glob pattern complexity

## Frequently Asked Questions

### What glob syntax does the MCP Filesystem server support?

The server supports standard `minimatch` glob syntax including `*` (wildcards), `**` (recursive directories), `?` (single character), and `!` (negation). Patterns like `**/*.ts` match TypeScript files at any depth, while `*.env` matches only files in the immediate directory, not subdirectories.

### How do I exclude directories like node_modules from search results?

Pass an array of exclusion patterns to the **`excludePatterns`** parameter, such as `["node_modules/**", "dist/**"]`. The server evaluates these patterns using `minimatch` before applying the main `pattern`, ensuring excluded paths never appear in results.

### Can I use glob patterns to search outside the allowed directories?

No. Every candidate path passes through `validatePath` in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts), which verifies the resolved absolute path remains within the server's configured allowed directories. Attempts to traverse upward using `..` or escape via symlinks are blocked regardless of the glob pattern used.

### What is the difference between pattern and excludePatterns parameters?

The **`pattern`** parameter defines which files to include in results (inclusion filter), while **`excludePatterns`** defines which files to omit (exclusion filters). The server first validates directory boundaries, then checks exclusions, and finally applies the inclusion pattern. Both accept glob strings, but `excludePatterns` accepts an array for multiple exclusion rules.