Grep.app API Endpoint and Query Parameter Format in grep-mcp

The grep-mcp tool communicates with the public Grep.app search service via a single HTTP GET request to https://grep.app/api/search, using a query string format that combines a base q parameter with optional f.* field filters for language, repository, and path constraints.

The galprz/grep-mcp repository implements a Model Context Protocol (MCP) server that proxies search requests to Grep.app's public API. Understanding the specific endpoint structure and query parameter encoding is essential for developers extending the tool or debugging search behavior.

Grep.app API Endpoint Structure

Base URL and Path

According to the source code in src/grep_mcp/server.py, the tool constructs requests to a single static endpoint:

# Line 27 in src/grep_mcp/server.py

url = "https://grep.app/api/search"

This URL serves as the base for all search operations performed by the grep_query function.

Core Query Parameters

The API requires at least one parameter to function:

Parameter	Required	Description
q	Yes	The raw search query string (e.g., asyncio.wait_for or class BaseModel).

When the grep_query tool is invoked with only a search term, the resulting HTTP request contains only this base parameter.

Query Parameter Format and Filter Syntax

The f.* Field Filter Convention

Grep.app implements a specialized query string convention for filtering results by metadata fields. The tool supports three optional filters, each prefixed with f.:

Parameter Key	Value Format	Example
f.lang	Programming language name (case-sensitive)	Python, JavaScript, Go
f.repo	GitHub repository in owner/repo format	fastapi/fastapi, galprz/grep-mcp
f.path	Directory or file path within the repository	src/, fastapi/main.py

These parameters are URL-encoded when transmitted. For example, the forward slash in owner/repo becomes %2F.

Building Parameter Dictionaries

In src/grep_mcp/server.py (lines 13-26), the tool constructs a Python dictionary called params that maps these keys to values:

# Lines 13-26 in src/grep_mcp/server.py

params = {"q": query}
if language:
    params["f.lang"] = language
if repo:
    params["f.repo"] = repo
if path:
    params["f.path"] = path

This dictionary is then passed to aiohttp's request method, which automatically handles URL encoding and query string assembly.

Implementation in grep-mcp Source Code

The API interaction logic resides primarily in two locations:

File	Function	Purpose
src/grep_mcp/server.py	grep_query()	Builds the params dictionary (lines 13-26) and executes the HTTP GET request to https://grep.app/api/search (line 27).
src/grep_mcp/__main__.py	Module entry point	Initializes the MCP server and registers the grep_query tool, making the API accessible via the Model Context Protocol.

The grep_query function is an async Python function that uses aiohttp to perform non-blocking HTTP requests to the Grep.app endpoint.

Practical Usage Examples

Basic Search Query

To search for a specific code pattern across all indexed repositories:

from grep_mcp.server import grep_query

# Search for asyncio timeout patterns

result = await grep_query("asyncio.wait_for")

This generates the request:

GET https://grep.app/api/search?q=asyncio.wait_for
Accept: application/json

Filtered Search with Multiple Parameters

To constrain results to a specific language, repository, and path:

result = await grep_query(
    query="class BaseModel",
    language="Python",
    repo="fastapi/fastapi",
    path="fastapi/"
)

This constructs the URL:

https://grep.app/api/search?q=class+BaseModel&f.lang=Python&f.repo=fastapi%2Ffastapi&f.path=fastapi%2F

Summary

• Endpoint: The grep-mcp tool targets https://grep.app/api/search for all search operations.
• Query Structure: Requests require a q parameter containing the search term, with optional f.lang, f.repo, and f.path filters for precise targeting.
• Implementation: Parameter construction occurs in src/grep_mcp/server.py (lines 13-26), with the HTTP request executed at line 27 using aiohttp.
• Encoding: Repository paths and directory paths are URL-encoded (e.g., / becomes %2F) when transmitted to the API.

Frequently Asked Questions

What is the exact URL endpoint used by grep-mcp to search code?

The tool sends GET requests to https://grep.app/api/search. This endpoint is hardcoded in src/grep_mcp/server.py at line 27 and serves as the single entry point for all code search operations performed by the MCP server.

How do I filter search results by programming language using the grep.app API?

Include the f.lang query parameter with the exact language name (e.g., Python, JavaScript, Go). In the grep-mcp implementation, this is added to the params dictionary in src/grep_mcp/server.py when the language argument is provided to the grep_query function.

Can I search within a specific GitHub repository using grep-mcp?

Yes, by providing the repo parameter in owner/repo format (e.g., fastapi/fastapi). The tool maps this to the f.repo query parameter. Note that the forward slash is URL-encoded to %2F when the request is transmitted to the Grep.app API endpoint.

What happens if I provide a path filter without specifying a repository?

The f.path parameter can be used independently to filter by directory structure across all indexed repositories, though it is most effective when combined with f.repo to target specific paths within a known codebase. The grep-mcp tool adds this parameter via params["f.path"] in src/grep_mcp/server.py when the path argument is supplied.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}