FindFiles MCP server

This MCP server provides an advanced file search tool allowing you to find files across your system using various filtering options such as wildcards, file attributes, content search, and more. The tool is particularly powerful for searching multiple directories simultaneously with fine-grained control over search parameters.

Installation

To install the FindFiles MCP server, you need to add it to your MCP configuration. This can be done by modifying your MCP configuration file with the following entry:

{
    "mcpServers": {
        "find-files": {
            "command": "npx",
            "args": [
                "-y",
                "find-files-mcp",
                "/Users/kst/Downloads",
                "/Users/kst/Desktop",
                "/Users/kst/Documents"
            ]
        }
    }
}

You can customize the default search directories by modifying the paths in the args array. The example above configures the search to look in the Downloads, Desktop, and Documents folders.

Usage

The FindFiles tool supports numerous parameters to refine your search. Here's how you can use each feature:

Basic Search Parameters

• directories: Specify one or more directories to search in
• filename: Enter a specific filename or use wildcards like *.txt or doc*
• extension: Filter by file extension (e.g., "pdf", "jpg")
• recursive: Set to false to prevent searching in subdirectories (default: true)

File Attribute Filters

• minSize and maxSize: Limit results by file size in bytes
• createdAfter and createdBefore: Filter by creation date (format: YYYY-MM-DD)
• modifiedAfter and modifiedBefore: Filter by modification date (format: YYYY-MM-DD)

Content and Type Filters

• contentSearch: Search within the contents of text files
• fileType: Filter by general file type categories: text, image, audio, video, application
• caseSensitive: Set to true to make filename matching case-sensitive (default: false)

Search Limitations

• maxResults: Limit the number of results returned (default: 1000)
• timeoutMs: Set maximum search duration in milliseconds (default: 30000)

Example Queries

Here are some example queries to help you get started:

Find all PDF files in default directories:

{
  "extension": "pdf"
}

Search for recent text files containing specific content:

{
  "fileType": "text",
  "modifiedAfter": "2023-01-01",
  "contentSearch": "important project"
}

Find large image files with a specific naming pattern:

{
  "filename": "IMG_*",
  "fileType": "image",
  "minSize": 5000000
}

Search in a specific directory without recursion:

{
  "directories": ["/Users/username/Projects"],
  "recursive": false,
  "extension": "js"
}

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.