{"id":28423314,"url":"https://github.com/rjtpp/mcp-server-file-search-tool","last_synced_at":"2026-05-19T14:10:03.498Z","repository":{"id":296444666,"uuid":"977945297","full_name":"RJTPP/mcp-server-file-search-tool","owner":"RJTPP","description":"A Model Context Protocol (MCP) server for searching file content with regex across various file types","archived":false,"fork":false,"pushed_at":"2025-07-28T10:36:00.000Z","size":165,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-28T12:27:26.764Z","etag":null,"topics":["llm","mcp","mcp-server","toolcalling"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RJTPP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-05T08:21:24.000Z","updated_at":"2025-07-28T10:36:04.000Z","dependencies_parsed_at":"2025-05-31T03:34:26.667Z","dependency_job_id":"0b9eb6fc-01ee-4be7-ba85-bd9b54a67f9d","html_url":"https://github.com/RJTPP/mcp-server-file-search-tool","commit_stats":null,"previous_names":["rjtpp/mcp-server-file-search-tool"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/RJTPP/mcp-server-file-search-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJTPP%2Fmcp-server-file-search-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJTPP%2Fmcp-server-file-search-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJTPP%2Fmcp-server-file-search-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJTPP%2Fmcp-server-file-search-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RJTPP","download_url":"https://codeload.github.com/RJTPP/mcp-server-file-search-tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJTPP%2Fmcp-server-file-search-tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278903016,"owners_count":26065786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["llm","mcp","mcp-server","toolcalling"],"created_at":"2025-06-05T08:37:18.779Z","updated_at":"2025-10-08T06:44:19.281Z","avatar_url":"https://github.com/RJTPP.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Server - File Search Tool 🗂️\n\nAn MCP (Model Context Protocol) server that provides powerful file system search and inspection capabilities via the MCP protocol. Use this tool to list directories, search file names, read file contents (including PDF and DOCX), and perform regex‑based content searches with context.\n\n## Features\n\n- **List file paths**: Breadth‑first or depth‑first listing, with paging and nested‑level control.  \n- **Search file names**: Regex‑based file name search.  \n- **Read files**: Read text, PDF, and DOCX files with optional character limits.  \n- **Search file contents**: Regex‑based content search with configurable context lines.  \n- **Allowed paths**: Restrict server to only browse and search within configured directories.  \n- **Exclude paths**: Prevent sensitive directories from being accessed.  \n- **Hide hidden files**: Optionally ignore files and directories beginning with a dot.  \n- **Path masking**: Replace configured path segments with tokens for privacy.  \n\n### Prerequisites\n\n- [Python](https://www.python.org) 3.10 or higher\n- [uv](https://github.com/astral-sh/uv) - Fast Python package manager\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/RJTPP/mcp-server-file-search-tool\ncd mcp-server-file-search-tool\n```\n\n2. Create virtual environment and install dependencies:\n```bash\nuv sync\n```\n\n### Running the Server\n\nStart the server (default port 6277):\n```bash\nuv run server.py\n```\n\n## Claude Desktop Integration\n\nTo add this server to Claude Desktop:\n\n```bash\nmcp install server.py --name \"File Search Tool\"\n```\n\nOr manually add it to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"File Search Tool\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/mcp-sever-file-search-tool/\",\n        \"run\",\n        \"--with\",\n        \"mcp[cli]\",\n        \"mcp\",\n        \"run\",\n        \"server.py\"\n      ]\n    }\n  }\n}\n```\n\n## Configuration\n\n1. Copy the example configuration:\n\n```bash\n   cp config_example.json config.json\n   ```\n\n2. Edit config.json to customize:\n\n```json\n{\n  \"DEFAULT_TIME_LIMIT\": 10,\n  \"HIDE_HIDDEN_FILES\": true,\n  \"HOST\": \"127.0.0.1\",\n  \"PORT\": 6277,\n  \"ALLOWED_PATHS\": [\n    \"/path/to/allowed/directory\"\n  ],\n  \"EXCLUDE_PATHS\": [\n    \"/path/to/excluded/directory\"\n  ],\n  \"PATH_MASKER\": {\n    \"ENABLED\": true,\n    \"MODE\": \"segment\",\n    \"MASK_TOKEN\": \"MASK\",\n    \"LOOK_FOR\": [\n      \"path_to_mask\"\n    ]\n  }\n}\n```\n\n### Required Fields\n\n- `ALLOWED_PATHS` is **required**. The server will not start unless at least one allowed path is configured.\n\n### Configuration Field Descriptions\n\n| Field                     | Type            | Description                                                                 |\n|--------------------------|-----------------|-----------------------------------------------------------------------------|\n| `DEFAULT_TIME_LIMIT`     | `int`           | Max execution time for searches (in seconds).                              |\n| `HIDE_HIDDEN_FILES`      | `bool`          | If `true`, ignores files and directories that start with `.`               |\n| `HOST`                   | `string`        | IP address the server will bind to (e.g., `\"127.0.0.1\"`).                  |\n| `PORT`                   | `int`           | Port number to listen on (e.g., `6277`).                                   |\n| `ALLOWED_PATHS`          | `list[string]`  | **Required.** Directories the server is allowed to access and search.      |\n| `EXCLUDE_PATHS`          | `list[string]`  | Directories to explicitly block, even if inside allowed paths.             |\n| `PATH_MASKER`            | `object`        | Optional masking settings for privacy.                                     |\n| `PATH_MASKER.ENABLED`    | `bool`          | Enables or disables path masking.                                          |\n| `PATH_MASKER.MODE`       | `\"segment\"` or `\"prefix\"` | Masking mode: `\"segment\"` replaces matching segments; `\"prefix\"` masks full path prefixes. |\n| `PATH_MASKER.MASK_TOKEN` | `string`        | The token to replace matched path segments (e.g., `\"MASK\"`).               |\n| `PATH_MASKER.LOOK_FOR`   | `list[string]`  | List of path segments to be masked when found in full paths.               |\n\n\n## Security\n\n\u003e [!WARNING]\n\u003e This server does **not** implement authentication or encryption.  \n\u003e It is designed **for local, personal use only**.\n\u003e Do **not** expose the server to untrusted networks or use it in production without adding proper security measures.\n\n\n## License\n\nThis project is released under the [MIT License](LICENSE).\n\nYou are free to use, modify, and distribute this software under the terms of the MIT License. See the LICENSE file for detailed terms and conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjtpp%2Fmcp-server-file-search-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frjtpp%2Fmcp-server-file-search-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjtpp%2Fmcp-server-file-search-tool/lists"}