# Maximum Allowed Query Length in grep-mcp: 1000 Character Limit and Error Handling

> Discover grep-mcp's 1000 character query limit. Learn how exceeding it causes an error and prevents API calls. Understand grep-mcp error handling.

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

---

**The maximum allowed query length in grep-mcp is 1000 characters; exceeding this limit triggers an immediate error return without contacting the grep.app API.**

The `grep-mcp` repository implements a hard limit on query string length to prevent invalid API requests. This validation occurs before any network traffic is initiated, ensuring that overly long queries fail fast with a descriptive error message. Understanding this constraint is essential when building MCP (Model Context Protocol) integrations that rely on the `grep_query` tool.

## Where Query Length Validation Occurs in grep-mcp

The query length check resides in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) at line 185. This location handles the `grep_query` tool implementation and performs input sanitization before constructing the API request.

According to the source code, the function explicitly checks the character count of the `query` parameter:

```python
if len(query) > 1000:
    return "❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query."

```

This early-return pattern prevents unnecessary network overhead and API rate limit consumption. The validation logic is part of the core server implementation exposed through [`src/grep_mcp/__init__.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/__init__.py), which registers the tool with the MCP framework.

## What Happens When You Exceed the Maximum Query Length

When a query string exceeds 1000 characters, `grep-mcp` immediately returns an error string without contacting the grep.app API. The error message follows this exact format:

```

❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query.

```

This behavior ensures that:
- No invalid requests reach the external API
- Users receive immediate feedback about query length constraints
- Network resources are conserved for valid queries

The error surfaces directly to the MCP client, allowing AI assistants to detect the failure and suggest query refinement strategies to users.

## Code Examples: Valid and Invalid Queries

The following examples demonstrate the 1000-character boundary in `grep-mcp`:

### Valid Query (Under 1000 Characters)

```python
from grep_mcp import grep_query

# 50 characters - well within limit

result = await grep_query("asyncio timeout handling patterns")
print(result)  # Returns JSON with search results

```

### Invalid Query (Exceeds 1000 Characters)

```python
from grep_mcp import grep_query

# Generate 1001 characters

long_query = "x" * 1001

error = await grep_query(long_query)
print(error)

# Output: ❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query.

```

In production MCP environments, the tool would surface this error to the assistant, which could then prompt the user to break the query into smaller segments or remove unnecessary terms.

## Why the 1000 Character Limit Exists

The **maximum allowed query length in grep-mcp** aligns with the underlying grep.app API constraints. By enforcing this limit client-side, the repository:

1. **Prevents API errors** that would result from over-length queries
2. **Reduces latency** by failing fast before network transmission
3. **Conserves rate limits** on the grep.app service
4. **Improves user experience** through clear, actionable error messages

The validation at `src/grep_mcp/server.py:185` serves as a guardrail that maintains compatibility between the MCP tool and the external search service.

## Summary

- The **maximum allowed query length in grep-mcp** is **1000 characters**, enforced in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) at line 185.
- Exceeding this limit triggers an immediate error return: `"❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query."`
- No API request is made when the limit is exceeded, conserving network resources and providing fast feedback.
- The constraint aligns with grep.app API limitations and ensures reliable MCP tool operation.

## Frequently Asked Questions

### What is the exact maximum query length allowed in grep-mcp?

The exact maximum query length is **1000 characters**. This limit is hardcoded in the query validation logic within [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) at line 185. Any string exceeding this length, including whitespace and special characters, will trigger the length validation error.

### Does grep-mcp truncate long queries automatically?

No, `grep-mcp` does not truncate long queries. Instead, it performs a strict validation check and returns an error message immediately if the query exceeds 1000 characters. The function returns the string: `"❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query."` without contacting the grep.app API.

### Where in the source code is the query length check implemented?

The query length validation is implemented in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) at line 185. This location is within the `grep_query` tool function, which handles the MCP tool execution. The check occurs before any network request construction, serving as an early validation gate for input parameters.

### What happens if I send a query with exactly 1000 characters?

A query with exactly 1000 characters is considered valid and will be processed normally. The validation logic uses a greater-than comparison (`len(query) > 1000`), so 1000-character queries pass the check and proceed to the grep.app API call. Only queries of 1001 characters or more trigger the error response.