GitHub Search MCP Server

A Model Context Protocol (MCP) server for searching and exploring GitHub repositories. Compatible with OpenAI's ChatGPT and Responses API.

Features

• 5 MCP Tools with readOnlyHint annotations:

  1. clone_repository - Clone repositories from a whitelisted GitHub user
  2. search_code - Fast grep-based code search with regex support
  3. get_tree - Display repository directory structure
  4. read_file - Read file contents with line range support
  5. get_outline - Extract code structure (classes, functions, methods)

• No Authentication Required - Server handles GitHub PAT internally

• Streamable HTTP Transport - Compatible with OpenAI's MCP integration

• MCP Protocol 2025-06-18 - Latest specification compliance

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your GitHub PAT token

3. Run the Server

python main.py

The server will start on http://localhost:8000.

Docker

# Build
docker build -t github-mcp-server .

# Run
docker run -p 8000:8000 -e GITHUB_PAT=your_token github-mcp-server

API Endpoints

Endpoint	Method	Description
/	GET	Server info and available endpoints
/mcp	POST	MCP protocol endpoint (JSON-RPC)
/health	GET	Health check
/capabilities	GET	Server capabilities

MCP Tools

clone_repository

Clone a GitHub repository from the whitelisted user.

{
  "name": "clone_repository",
  "arguments": {
    "repo_name": "my-repo"
  }
}

search_code

Search for code patterns using grep.

{
  "name": "search_code",
  "arguments": {
    "repo_name": "my-repo",
    "pattern": "def main",
    "file_pattern": "*.py",
    "case_sensitive": false,
    "max_results": 50
  }
}

get_tree

Display repository directory tree.

{
  "name": "get_tree",
  "arguments": {
    "repo_name": "my-repo",
    "path": "src",
    "max_depth": 3,
    "show_hidden": false
  }
}

read_file

Read file contents with optional line ranges.

{
  "name": "read_file",
  "arguments": {
    "repo_name": "my-repo",
    "file_path": "src/main.py",
    "start_line": 1,
    "end_line": 50
  }
}

get_outline

Get code outline showing classes and functions.

{
  "name": "get_outline",
  "arguments": {
    "repo_name": "my-repo",
    "file_path": "src/main.py"
  }
}

Connecting to ChatGPT

1. Deploy the server to a public URL (e.g., Railway, Render, or AWS)
2. In ChatGPT, go to Settings > Connectors > Add Connector
3. Enter your server URL (e.g., https://your-server.com/mcp)
4. Select "No authentication required"

Security

• Whitelisted User: Only repositories from the configured ALLOWED_USERNAME can be cloned
• Path Traversal Prevention: All file paths are validated
• No Secrets in Responses: GitHub PAT is server-side only

Environment Variables

Variable	Description	Default
GITHUB_PAT	GitHub Personal Access Token	(empty)
HOST	Server host	0.0.0.0
PORT	Server port	8000
REPO_STORAGE_PATH	Path for cloned repos	/tmp/repos
ALLOWED_USERNAME	Whitelisted GitHub username	anirudhadasgupta

License

MIT