GitHub Search MCP Server

# 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 ```bash pip install -r requirements.txt ``` ### 2. Configure Environment ```bash cp .env.example .env # Edit .env with your GitHub PAT token ``` ### 3. Run the Server ```bash python main.py ``` The server will start on `http://localhost:8000`. ## Docker ```bash # 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. ```json { "name": "clone_repository", "arguments": { "repo_name": "my-repo" } } ``` ### search_code Search for code patterns using grep. ```json { "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. ```json { "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. ```json { "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. ```json { "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