Allows advanced GitHub code search with filtering and content retrieval, enabling LLMs to search repositories by keywords, file names, and retrieve file contents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-github-advanced-search search for files named clinerules"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A powerful Model Context Protocol (MCP) server that enables Large Language Models to perform advanced GitHub code searches with intelligent filtering and content retrieval capabilities, optimized for DeepSeek integration.
The GitHub Advanced Search (G.A.S.) MCP server provides LLMs with sophisticated GitHub search capabilities that go beyond standard API limitations. Using web automation with Playwright, it enables deep code discovery, pattern analysis, and content retrieval across the entire GitHub ecosystem. This version includes enhanced support for DeepSeek models, providing tailored search results and structured JSON output.
Related MCP server: GitHub Search MCP Server
tested using vscode + cline + openrouter:deepseek/deepseek-r1-0528:free
# step1: init gas
gas_entrypoint
# step2: feed model
gas_search_code
file_name: clinerules
# step3: make your wish
You are now have better knowledge of `clinerules`
please keep the current file format and deep level
enhance the `<file-path-to-clinerules>`🔍 Advanced GitHub Search: Search by keywords, file names, and complex filters
📁 Content Retrieval: Automatically fetch and return file contents
🤖 LLM Integration: Seamless integration with Claude, GPT, and other MCP-compatible LLMs
🔄 Pagination Support: Handle large result sets with intelligent pagination
🌐 Web Automation: Uses Playwright for robust GitHub interaction
📊 Structured Results: Returns organized JSON data with repository links, file links, and content
⚡ High Performance: Async operations with concurrent file downloads
🔐 Authentication Support: Works with GitHub login for private repositories
🤖 DeepSeek Integration: Optimized for use with DeepSeek models, providing tailored search results and structured JSON output
graph TB
subgraph "MCP Client (LLM)"
A[Claude/GPT/Other LLM]
end
subgraph "MCP Server (G.A.S.)"
B[MCP Server]
C[Search Engine]
D[Playwright Browser]
E[Content Fetcher]
F[Result Processor]
end
subgraph "GitHub"
G[GitHub Search]
H[Repository Files]
I[Raw Content]
end
A -->|MCP Protocol| B
B --> C
C --> D
D -->|Web Automation| G
G -->|Search Results| D
D --> E
E -->|HTTP Requests| I
I -->|File Content| E
E --> F
F -->|Structured Data| B
B -->|JSON Response| A
classDef client fill:#e1f5fe,stroke:#01579b,color:#01579b
classDef server fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
classDef github fill:#f3e5f5,stroke:#4a148c,color:#4a148c
class A client
class B,C,D,E,F server
class G,H,I githubsequenceDiagram
participant LLM as LLM Client
participant MCP as MCP Server
participant PW as Playwright Browser
participant GH as GitHub Search
participant API as GitHub Raw API
LLM->>MCP: gas_search_code(keyword, file_name)
MCP->>PW: Launch browser session
PW->>GH: Navigate to search URL
GH-->>PW: Search results page
PW->>PW: Extract repository & file links
loop For each page
PW->>GH: Navigate to page N
GH-->>PW: Results for page N
PW->>PW: Extract links from page
end
MCP->>API: Fetch file contents (async)
API-->>MCP: Raw file content
MCP->>MCP: Structure response data
MCP-->>LLM: JSON with repositories, files & content
alt More results available
LLM->>MCP: get_remaining_result(start_id)
MCP-->>LLM: Next batch of results
endPython 3.10 or higher
Node.js (for Playwright browser automation)
GitHub account (recommended for optimal functionality)
Install the package:
pip install mcp-server-git-gasInstall Playwright browsers:
playwright install chromium💀Not tested Configure your MCP client (e.g. claude desktop):
Add to your claude_desktop_config.json:
# not tested !!!
{
"mcpServers": {
"github-advanced-search": {
"command": "mcp-server-git-gas",
"args": []
}
}
}Once configured, you can start searching GitHub through your LLM:
Search GitHub for Python files containing "async def" functionsThe LLM will automatically use the G.A.S. tools to perform the search and return structured results.
$ cd ~
$ git clone --depth=1 https://github.com/louiscklaw/mcp-github-advanced-search ~/mcp/mcp-git-gas# Install Playwright browsers
$ playwright install chrome
$ playwright install --deps# this will create the user_data_dir for chromium
# go login google or any other service you want
$ cd ~/mcp/mcp-git-gas
$ ./seedChromeUserDataDir.sh{
"mcp": {
"servers": {
"git-gas": {
"autoApprove": [
"get_remaining_result",
"gas_readme",
"gas_search_code"
],
"disabled": false,
"timeout": 300,
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"<USER_HOME_DIR>/mcp/mcp-git-gas/src/mcp_server_git_gas",
"run",
"mcp-server-git-gas"
]
}
}
}
}gas_entrypointInitialize and get information about the GitHub Advanced Search server.
Parameters: None
Returns: Server information and usage instructions with workflow diagram.
graph TD
a((start))
d((end))
b("search code with filter (gas_search_code)")
c("return search result")
c1("is the result finished ?")
c2("use get_remaining_result to list remaining result")
a --> b --> c --> c1 -- Yes --> d
c1 -- No --> c2
c2 --> c1gas_search_codeSearch GitHub repositories with advanced filters.
Parameters:
keyword (string, optional): Search keyword (single word recommended)
file_name (string, optional): Specific filename to search for (e.g., ".clinerules", "README.md")
Returns: Array of search results with:
[
{
"REPOSITORY_LINK": "https://github.com/owner/repo",
"FILE_LINK": "https://github.com/owner/repo/blob/main/file.py",
"RAW_UESR_CONTENT_LINK": "https://raw.githubusercontent.com/owner/repo/main/file.py",
"FILE_CONTENT": "actual file content..."
}
]get_remaining_resultRetrieve additional results from a previous search (pagination).
Parameters:
start_id (integer): Starting index for the next batch of results
Returns: Next batch of search results with the same structure as gas_search_code.
call `gas_entrypoint` to initialize yourselfHi,
please use `gas_search_code` with below json
{
"keyword": "mcp mermaid",
"file_name": "README.md"
}
and understand the content returned, i will send you the task afterwards.
i am working on a python project,
please task a look to the source code of the project.
with the help from files in former results.
please help to and update the README file.
The server uses Playwright with persistent browser context for:
Session management
Authentication state preservation
Improved performance
Browser data is stored in: ~/mcp/mcp-git-gas/_user_data_dir
# Clone the repository
git clone <repository-url>
cd mcp-server-git-gas
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts/activate
# Install dependencies
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytestsrc/mcp_server_git_gas/
├── __init__.py # CLI entry point
├── server.py # Main MCP server implementation
├── CONST.py # Configuration constants
├── fetch_data.py # Async HTTP client
├── fetchFileContent.py # File content retrieval
├── convertFileLinkToRaw... # URL conversion utilities
├── url_util.py # URL building helpers
└── git_dump_screen.py # Debug utilitiesMCP Server: Implements the Model Context Protocol interface
Search Engine: Handles GitHub search logic and pagination
Content Fetcher: Retrieves file contents asynchronously
Browser Automation: Playwright-based GitHub interaction
# Test the server with MCP inspector
npx @modelcontextprotocol/inspector uvx mcp-server-git-gas# Build development image
docker build -t mcp/git-gas:dev .
# Run with volume mount for development
docker run --rm -i \
-v $(pwd):/app \
mcp/git-gas:devSearch Initiation: LLM calls gas_search_code with search parameters
Query Building: Server constructs GitHub search URL with filters
Web Automation: Playwright navigates GitHub search pages
Result Extraction: JavaScript execution extracts repository and file links
Content Retrieval: Parallel HTTP requests fetch file contents
Response Formatting: Results structured as JSON for LLM consumption
"Not logged in" errors
Solution: run seedChromeUserDataDir.sh to start a browser and perform login
No results found
Check search keywords for typos
Try broader search criteria
Verify GitHub is accessible
Browser launch failures
Run: playwright install chromium
Check system requirements for Playwright
Rate limiting
GitHub may rate limit requests
The server includes delays and retry logic
Consider using authenticated sessions for higher limits
Debug screenshots are saved to: ~/mcp_github_advanced_search/debug.png
Search Speed: ~2-5 seconds per search page
Concurrent Requests: Up to 10 parallel file downloads
Result Limits: 20 results per search (configurable)
Pagination: Supports up to 2 pages (100+ results)
GitHub Authentication: Login to GitHub in the browser for optimal results
Rate Limiting: Respects GitHub's usage policies
Browser Requirements: Requires Chromium browser (installed via Playwright)
Network Dependencies: Requires internet connection for GitHub access
We welcome contributions! Please see our Contributing Guidelines for details.
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
Built on the Model Context Protocol by Anthropic
Uses Playwright for browser automation
Inspired by the need for advanced GitHub search capabilities in LLM workflows
Thanks to the MCP community for feedback and contributions
Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki
Note: This server requires a GitHub account for optimal functionality. Some features may be limited when used without authentication.
initialize git-gas, no parameters required
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'initialize' implies a state-changing operation, but the description does not mention side effects, idempotency, permissions, or expected output. The only disclosed constraint, 'no parameters required', merely restates the schema and adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with the primary action front-loaded before the parametric note. It is appropriately sized for a parameterless tool and contains no redundant fluff, though 'no parameters required' is already evident from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits important contextual details: what initialization produces, whether it must be run before other commands, and what a successful call returns. There is no output schema to cover return values, so the description should have supplied this context but does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already documents an empty properties object, so the baseline of 4 applies. The phrase 'no parameters required' adds no new meaning but is consistent with the schema. There is no parameter coverage gap to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action, 'initialize git-gas', with a clear verb and resource. It distinguishes the tool from its siblings (gas_search_code, get_remaining_result, git_helloworld) by indicating a setup operation rather than a search or retrieval. It lacks detail on what 'initialize' entails, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no indication that initialization is required before using sibling tools. 'no parameters required' addresses invocation constraints but not usage context. An agent has to infer that this is a setup step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This is a utilities that search github with advanced filters (e.g. keyword)
the result is in json format with below fields"
[
{
"REPOSITORY_LINK": "<repository-found>",
"FILE_LINK": "<file-found>",
"RAW_USER_CONTENT_LINK": "<download-link-to-the-file>",
"FILE_CONTENT": "<downloaded-content>"
},
{...},
{...},
{...},
{"next_instructions_md": "<contains-the-instruction-to-get-the-remaining-result>"}
]when you receive this,
please ensure you follow the next_instructions_md to collect all results.
You can use memory, sequential-thinking, structured-argumentation to help solving problems.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | No | the keyword user interested, e.g. `helloworld()` * Please limit the keyword to one single word only (e.g. `helloworld` and not `hello word`) default('') | |
| file_name | No | the file name user interested e.g. `.clinerules` default('') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full behavioral burden. It discloses the exact JSON output fields, the presence of next_instructions_md, and the need to follow it for remaining results. This is meaningful behavioral detail, even though auth and rate limits are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is cluttered with headings, a large JSON example, and an unrelated suggestion to use memory/sequential-thinking/structured-argumentation. It is structured but not front-loaded and contains non-essential content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully provides the response format and next-step instructions. However, it does not explain how gas_search_code relates to sibling tools gas_entrypoint and get_remaining_result, nor does it mention error or edge-case behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with keyword and file_name already described with examples and constraints. The description adds no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool searches GitHub with filters (keyword, file_name) and specifies the JSON response shape. It is clear about verb and resource, but it does not explicitly differentiate itself from siblings like gas_entrypoint or get_remaining_result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'search github with advanced filters' and instructs the agent to follow next_instructions_md to collect all results. However, it lacks explicit guidance on when to prefer this tool over siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This is a tools to get the remaining data searched by gas_search_code.
the result is in json format with below fields.
[
{
"REPOSITORY_LINK": "<repository-found>",
"FILE_LINK": "<file-found>",
"RAW_USER_CONTENT_LINK": "<download-link-to-the-file>",
"FILE_CONTENT": "<downloaded-content>"
},
{...},
{...},
{...},
{"next_instructions_md": "<contains-the-instruction-to-get-the-remaining-result>"}
]When you receive this,
please ensure you follow the next_instructions_md to collect all results.
You can also use memory, sequential-thinking, structured-argumentation to help solving problems.
| Name | Required | Description | Default |
|---|---|---|---|
| start_id | No | start pointer for return the remaining result default('0') | 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does a good job by specifying the exact JSON result shape, the fields returned, and the role of next_instructions_md in chaining further calls. It does not mention failure modes or rate limits, but for a read-style continuation tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The JSON example is useful and the structure is readable, but the description includes minor fluff and a typo ('This is a tools'), and the closing sentence about memory/sequential-thinking is not directly relevant to tool invocation. It is adequate but not tightly edited.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output format is described in detail, compensating for the missing output schema and making return values predictable. However, the description leaves the pagination termination condition and the relationship between start_id and next_instructions_md implicit, so an agent may not know exactly when to stop or what value to pass.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents start_id as a 'start pointer' with a default of 0 and has 100% description coverage, so the description does not need to restate it. The description adds context about remaining data and next_instructions_md but not concrete guidance on how to derive or increment start_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets 'remaining data' from a prior gas_search_code search, naming the source tool and implying a continuation role. It does not explicitly contrast sibling tools, but 'remaining data searched by' is specific enough to distinguish it from the initial search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used after gas_search_code to collect remaining results, and instructs the agent to follow next_instructions_md. However, it never gives an explicit when-to-use versus when-not-to-use rule nor names an alternative tool, leaving the pagination workflow to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
my helloworld call
| Name | Required | Description | Default |
|---|---|---|---|
| test_input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and a description that reveals nothing about side effects, permissions, return values, or any behavioral traits, an agent is completely blind to what happens when this tool is invoked. The description adds zero value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While short, this is under-specification rather than conciseness. The sentence 'my helloworld call' carries no operational information and does not earn the little space it occupies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a required parameter and no output schema or annotations, the description should compensate. It provides nothing, making the tool unusable for an agent without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter test_input with no description, and schema description coverage is 0%. The description does not explain what test_input means, its format, or its purpose, leaving the agent entirely unguided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'my helloworld call' is essentially a tautology of the tool name git_helloworld. It provides no specific verb, resource, or scope, and gives an agent no way to understand what the tool actually does or how it differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool vs. alternatives. Sibling tools like gas_entrypoint and gas_search_code exist, but there is no mention of them or any conditions for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.2gas_entrypointgas_search_codeget_remaining_resultgit_helloworldScored across 4 tools
The core tools gas_search_code and get_remaining_result are clearly paired, but git_helloworld is a placeholder and gas_entrypoint's purpose relative to searching is vague. An agent could waste calls trying to determine which tool actually serves the search workflow.
Names mix prefixes like git_ and gas_ with a verb-first name like get_remaining_result, and gas_entrypoint does not follow the same pattern as gas_search_code. git_helloworld also feels unrelated to the domain, making the naming set inconsistent.
Four tools is a reasonable count, but one is a hello-world stub and another is an unclear initializer, leaving only two tools that actually support the advanced-search purpose. The total count is acceptable, but the composition is weak.
Search plus pagination covers the basic GitHub search and result-retrieval workflow, which is good. However, the gas_entrypoint setup step is unexplained and the search surface seems limited to keyword matching, leaving minor gaps around options and workflow clarity.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Dive into the world of open-source with the GitHub Repo Explorer! Utilize the powerful GitHub
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Finds real, maintained open-source repos that fit your project. MCP grounding for coding agents.
