Skip to main content
Glama
agentic-search-mcp

agentic-search-mcp

agentic-search-mcp

A minimal Model Context Protocol server that gives an MCP client three filesystem tools: read, glob, and grep.

Every path is resolved against a single search root. The agent can only see files inside that root; paths that escape it (including through symlinks) are rejected. Only text files are read, and common generated directories (.git, .venv, node_modules, __pycache__, ...) are skipped during searches.

Requirements

  • Python 3.10+

  • uv

Related MCP server: personal-mcp-bridge

Install

cd agentic-search-mcp
uv sync

This creates a .venv with the server and its mcp dependency installed. To also install the optional dependencies for the example client, use uv sync --extra examples.

Run the server

The server communicates over stdio, which is how an SDK client (such as the OpenAI Agents SDK example below) launches it. Set the folder it is allowed to search, then start it:

export AGENTIC_SEARCH_ROOT=/path/to/your/project
uv run agentic-search-mcp

AGENTIC_SEARCH_ROOT defaults to the current working directory if it is not set. One server process serves one root; start a separate server for each folder you want to expose.

Tools

Tool

Description

Key arguments

read

Read a text file as numbered lines.

path, offset=0, limit=2000

glob

Match files/directories with a pathlib-style glob.

pattern, path=".", max_results=1000

grep

Regex (Python re) or literal search over file contents.

pattern, path=".", glob_filter=None, literal=False, ignore_case=False, max_results=100

Paths may be absolute or relative to the search root. Typical calls:

  • read(path="src/main.py", offset=0, limit=100)

  • glob(pattern="**/*.py", path="src")

  • grep(pattern="def .*config", glob_filter="*.py", path=".")

  • grep(pattern="TODO", literal=True, ignore_case=True, glob_filter="*.md")

grep patterns use Python re syntax per line: | means "or", .* matches any run of characters, and (a|b) groups alternatives. Do not escape | — GNU grep's \| syntax is not supported. Use literal=True for plain text, ignore_case=True for case-insensitive matching, and max_results to cap the output. A missing read path returns the closest matching file names to help the agent correct itself; agents should confirm paths with glob before reading.

Invalid calls (missing file, directory passed to read, invalid regex, or a path outside the root) return readable error text so the model can retry with a corrected call.

Example client

examples/openai_agents_client.py is a minimal client that launches the server as a subprocess, points it at a folder, and asks an agent a question. It uses the OpenAI Agents SDK with an OpenAI model.

uv sync --extra examples
export OPENAI_API_KEY=your-api-key

uv run --extra examples python examples/openai_agents_client.py \
  --root /path/to/your/project \
  --prompt "Find where configuration is loaded"

The default model is gpt-5.6-luna; override it with --model or OPENAI_MODEL. By default the agent is asked to list the Python files in the root if no --prompt is given, and --root defaults to the current directory.

The client passes the search root to the server with AGENTIC_SEARCH_ROOT and forwards PATH and HOME because the SDK replaces the child's environment. OPENAI_API_KEY stays in the client process and is never sent to the MCP server.

Available Tools

3 tools
globA

Find files and directories matching a glob pattern.

Args: pattern: A pathlib-style glob, e.g. **/*.py or src/**/*.ts. path: Directory to search within (absolute or root-relative, default root). max_results: Cap on returned matches (default 1000).

Inputs: pattern (required), path, max_results. Returns: result

grepA

Search file contents with a regular expression (or a literal string).

pattern is a Python re regular expression matched against each line with re.search -- it is not a shell grep command. Use | to combine alternatives, .* for wildcards, and groups/quantifiers such as (foo|bar) or \w+. \| matches a literal pipe character, so do not escape | to mean "or" (GNU grep basic-regex syntax is not used). For example::

grep(pattern="def (load|save)_config|class .*Settings|TODO.*(refactor|migrate)", glob_filter="*.py")

Set literal=True to match plain text with no regex interpretation. Use ignore_case for case-insensitive matching and max_results to cap output; there is no shell pipeline to pipe into head.

Args: pattern: Regular expression (Python re syntax), or literal text when literal is true. Combine alternatives with unescaped |. path: File or directory to search (absolute or root-relative, default root). glob_filter: Optional filename filter, e.g. *.py. literal: Treat pattern as plain text instead of a regex (default false). ignore_case: Case-insensitive matching (default false). max_results: Cap on returned matches (default 100).

Inputs: pattern (required), path, literal, glob_filter, +2 more. Returns: result

readA

Read a text file and return numbered lines.

Args: path: File path, absolute or relative to the search root. offset: Zero-based line number to start from (default 0). limit: Maximum number of lines to return (default 2000).

Inputs: path (required), limit, offset. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools map onto the classic, well-separated search primitives: file discovery (glob), content search (grep), and file inspection (read). There is no plausible way to confuse them, and the descriptions explicitly clarify boundaries (e.g. grep is regex, not shell grep; glob is for paths, not contents).

    Naming Consistency4/5

    All names are short, lowercase, unprefixed, and drawn from established CLI vocabulary, so the set reads predictably. The only minor deviation is that 'read' is a bare verb while 'glob' and 'grep' are tool-name nouns, but this matches developer expectations rather than causing confusion.

    Tool Count4/5

    Three tools is lean but deliberate for a focused read-only search server; each tool earns its place with no redundant overlap. It sits at the low end of the comfortable range, which is acceptable given how narrow the stated purpose is.

    Completeness4/5

    The surface covers the full read-only search lifecycle: find files, search their contents, then open and page through them, with filters and result caps that make each step composable. There are no write/edit or file-metadata operations, but those fall outside the implied search-and-read scope, so the gap is minor.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides a flexible lens into directory structures and files, enabling LLM clients to efficiently navigate and understand codebases with minimal noise. It offers secure, gitignore-aware file access with tools like directory listing, file reading, and grep-like search.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables safe, read-only browsing of allowlisted local directories through MCP, providing tools to list roots, read files, and search text.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables safe filesystem and git operations confined within a single allowed directory tree, using symlink-resolved path containment to protect against path traversal. Users can read, write, list, and search files, as well as initialize repos and run status, stage, commit, diff, and log operations through MCP.
      11
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to read only explicitly allowlisted Linux project files and selected Codex conversation turns. It supports listing projects and files, reading UTF-8 files, bounded text search, and paged reading of authorized conversations.
      MIT