MCP Client for GitHub Advanced Search (mcp-git-gas in short)

A powerful Model Context Protocol (MCP) server that enables LLM to perform advanced GitHub code searches with filtering and content retrieval capabilities, optimized for DeepSeek integration.

The GitHub Advanced Search (G.A.S.) MCP client 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.

tested using vscode + cline + openrouter:deepseek/deepseek-r1-0528:free

Example workflow

#prompt

# step1: init gas
gas_init

# step2: feed context
gas_search_code
file_name: clinerules

# step3: go ahead with your prompt
You are now have better knowledge of `clinerules`
please keep the current file format and deep level
enhance the `<file-path-to-clinerules>`

Key Features

• 🔍 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

under heavy development

Prerequisites

• Python 3.10 or higher
• package manager: uv
• WSL2 (Distro: ubuntu LTS)
• Node.js (for Playwright and browser automation)
• GitHub account

step1 (clone source)

cd ~
git clone --depth=1 https://github.com/louiscklaw/mcp-github-advanced-search ~/mcp/mcp-git-gas

step2 (install remaining dependencies, playwright)

# Install Playwright browsers
$ playwright install chrome
$ playwright install --deps

step3 seed chrome user credentials

# 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

step4 depends, add below configuration to your agent

VS Code with MCP Extension

{
  "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_init

caution: under heavy development

Initialize and get information about the GitHub Advanced Search server.

Parameters: None

Returns: Server information and usage instructions with workflow diagram.

gas_search_code

caution: under heavy development

Search 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")
• file_ext (string, optional): Specific file extension to filter by (e.g., ".py", ".md")

Returns: Array of search results with: T.B.A.

[
  {
    "REPOSITORY_LINK": "https://github.com/owner/repo",
    "FILE_LINK": "https://github.com/owner/repo/blob/main/file.py",
    "RAW_USER_CONTENT_LINK": "https://raw.githubusercontent.com/owner/repo/main/file.py",
    "FILE_CONTENT": "actual file content..."
  }
]

get_remaining_result

Retrieve 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.

step1

# prompt

gas_init

step2

# prompt

Hi,

please use `gas_search_code` with below json

{
  "keyword": "mermaid",
  "file_name": "README.md"
}

and understand the content returned, i will send you the task afterwards.

step3

# prompt

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.md` file.

Browser Configuration

The server uses Playwright with persistent browser context for:

• Session management
• Authentication state preservation
• Improved performance

Browser data is stored in: <USER_HOME>/mcp/mcp-git-gas/_user_data_dir

Local Development Setup

# Clone the repository
git clone <repository-url>
cd mcp-server-git-gas

# Install dependencies
pip install -e .

# start mcp debugging tools
npx @modelcontextprotocol/inspector uvx mcp-server-git-gas

Project Structure

src/mcp_server_git_gas       # source code folder
  - __main__.py              # entry point
docs                         # documentation folder
tests                        # tests folder

Key Components

• MCP 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

Testing with MCP Inspector

# Test the server with MCP inspector
npx @modelcontextprotocol/inspector uvx mcp-server-git-gas

🐋 Docker Development (NOT IMPLEMENTED)

it supposed to be able to handle the github user a/c within docker for better security

# 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:dev

1. Search Initiation: LLM calls gas_search_code with search parameters
2. Query Building: Server constructs GitHub search URL with filters
3. Web Automation: Playwright navigates GitHub search pages
4. Result Extraction: JavaScript execution extracts repository and file links
5. Content Retrieval: Parallel HTTP requests fetch file contents

updated at: 2025-Jul-18