MCP Client for GitHub Advanced Search

Link to repository

https://github.com/louiscklaw/mcp-github-advanced-search

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.

🔍 Overview

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.

Demo

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

youtube link to demo

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

🏗️ Architecture

under heavy development

🗺️ Search Workflow

🚀 Quick Start

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

⚙️ Configuration

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"]
      }
    }
  }
}

🛠️ Available Tools

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.

💡 Usage Examples

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.

⚙️ Configuration & Environment

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

🚧 Development

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

🔍 How It Works

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

Nextfolio uses custom MDX for blog posts, making it easy to include JSX components such as interactive embeds, charts, or alerts directly in your markdown content.

Here are some examples of using MDX:

h2 Heading

h3 Heading

h4 Heading

h5 Heading

Emphasis

This is bold text

This is italic text

Blockquotes

If today were the last day of my life, would I want to do what I am about to do today? – Steve Jobs

Links

• Nextfolio is built with Next.js.
• Nextfolio uses pnpm for package management.

CodeBlocks

// This is commented-out code
export default function HelloWorld() {
  return (
    <h1>Hello, World!</h1>
  );
}

Images

Nextfolio uses Next.js Image in MDX for seamless image rendering:

<Image
  src="/opengraph-image.png"
  alt="OpenGraph image"
  width={640}
  height={500}
/>

Renders:

Image Grid

Nextfolio uses a custom image grid component to display image galleries.

<ImageGrid
  columns={3} // Accepts 2, 3, or 4 columns
  images={[
    { src: "/photos/photo1.jpg", alt: "Photo1", href: "#" }, // 'href' is optional
    { src: "/photos/photo2.jpg", alt: "Photo2", href: "#" },
    { src: "/photos/photo3.jpg", alt: "Photo3"},
  ]}
/>

Renders:

Embeds

Tweets

Nextfolio uses react-tweet to embed tweets in MDX posts.

<StaticTweet id="1617979122625712128" />

Renders:

Andrej Karpathy

@karpathy

·Follow

The hottest new programming language is English

8:14 PM · Jan 24, 2023

48.3K

Reply

Copy link

Read 1.3K replies

YouTube Videos

Nextfolio uses react-youtube to embed YouTube videos in MDX posts.

<YouTube videoId="wXhTHyIgQ_U" />

Renders:

Captions

Nextfolio uses react-wrap-balancer to evenly balance captions in MDX posts.

<Caption>
  Captions that flow smoothly, making your content easy to read and visually
  appealing with a clean look.
</Caption>

Renders:

Tables

Nextfolio uses a custom table component to render tables in MDX posts.

<Table
  data={{
    headers: ["Title", "Description"],
    rows: [
      [
        "First item",
        "Lorem ipsum dolor sit amet consectetur adipisicing elit. Aliquid perspiciatis repellat amet quos.",
      ],
      [
        "Second item",
        "Lorem ipsum dolor sit amet consectetur adipisicing elit. Aliquid perspiciatis repellat amet quos.",
      ],
    ],
  }}
/>

Renders:

Math Expressions

Nextfolio allows you to render mathematical expressions in MDX posts using KaTeX . Simply wrap your expression in $ to include KaTeX within your MDX content.

$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$

Renders:

$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$

Callout

Nextfolio uses a custom callout component to render important information in MDX posts.

<Callout emoji="💡">
[Nextfolio](https://nextfolio.site) is a clean, simple, and fast portfolio built with Next.js, Tailwind CSS, and pnpm for optimal performance.
</Callout>

Renders: