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

> Discover the grep.app API endpoint and query parameter format used by grep-mcp. Learn how to construct effective search queries with q and f filters for precise code searching.

- Repository: [gal peretz/grep-mcp](https://github.com/galprz/grep-mcp)
- Tags: api-reference
- Published: 2026-02-16

---

**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`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py), the tool constructs requests to a single static endpoint:

```python

# 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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) (lines 13-26), the tool constructs a Python dictionary called `params` that maps these keys to values:

```python

# 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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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:

```python
from grep_mcp.server import grep_query

# Search for asyncio timeout patterns

result = await grep_query("asyncio.wait_for")

```

This generates the request:

```http
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:

```python
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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) when the `path` argument is supplied.