\n GitHub Repo MCP is an open-source MCP server that lets your AI assistants browse GitHub repositories, explore directories, and view file contents.\n
\n\n## Table of contents\n\n\n Getting started β’\n Feature overview\n
\n\n## β¨ Key features\n\n- π» Compatible with Cursor, Windsurf, Claude Desktop, and other MCP clients supporting `stdio` protocol\n- π Browse the contents of any public GitHub repository\n- π Navigate through repository directories and subdirectories\n- π View the content of code and text files\n- π¦ Easy installation via package manager\n\n## Getting Started\n\n### Prerequisites\n\nInstalling the server requires the following on your system:\n- Node.js 18+\n- npm or yarn\n\n### Step 1. Installation\n\nYou can install and run GitHub Repo MCP using NPX or setting in mcp.json of your IDE:\n\n#### MacOS\n\n```bash\nnpx github-repo-mcp\n```\n\n#### Windows NPX\n\n```bash\ncmd /c npx -y github-repo-mcp\n```\n\n#### Windows NPX via .cursor/mcp.json\n\n```json\n{\n \"mcpServers\": {\n \"github-repo-mcp\": {\n \"command\": \"wsl\",\n \"args\": [\n \"bash\",\n \"-c\",\n \"cmd /c npx -y github-repo-mcp\"\n ],\n \"enabled\": true\n }\n }\n}\n```\n\n#### Windows NPX via .cursor/mcp.json (if path not set)\n\n```bash\n# Find the full path to npx first\nwhich npx\n```\n\n```json\n{\n \"mcpServers\": {\n \"github-repo-mcp\": {\n \"command\": \"wsl\",\n \"args\": [\n \"bash\",\n \"-c\",\n \"'/home/[username]/.nvm/versions/node/v20.18.0/bin/npx github-repo-mcp'\"\n ],\n \"enabled\": true\n }\n }\n}\n```\n\n\nWait a few seconds or click on the refresh button a few times if it does not register. If it still won't register, make sure you entered the right command.\n\n### Step 2. Configuration\n\nThe GitHub Repo MCP server can use a GitHub token for higher rate limits when accessing the GitHub API.\n\n#### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GITHUB_TOKEN` | No | None | Your GitHub personal access token for higher rate limits |\n\n#### Setting Up a GitHub Token (Optional)\n\nWhile the server works without authentication, GitHub API has rate limits that are much lower for unauthenticated requests. To increase your rate limit:\n\n1. Create a personal access token at https://github.com/settings/tokens\n2. Set the token as an environment variable in mcp.json:\n\n```json\n{\n \"mcpServers\": {\n \"github-repo-mcp\": {\n \"command\": \"...\",\n \"args\": [\n ...\n ],\n \"env\": {\n \"GITHUB_TOKEN\": \"Your_Github_Token\"\n }\n \"enabled\": true,\n }\n }\n}\n```\n\n## Feature Overview\n\n### Repository Browsing Tools\n\nThe server provides three main tools for interacting with GitHub repositories:\n\n#### 1. `getRepoAllDirectories`\n\nLists all files and directories at the root of a GitHub repository.\n\n- **Parameters**:\n - `repoUrl`: The URL of the GitHub repository (e.g., \"https://github.com/owner/repo\")\n\n#### 2. `getRepoDirectories`\n\nLists contents of a specific directory in a GitHub repository.\n\n- **Parameters**:\n - `repoUrl`: The URL of the GitHub repository\n - `path`: The directory path to fetch (e.g., \"src\")\n\n#### 3. `getRepoFile`\n\nRetrieves and displays the content of a specific file from a GitHub repository.\n\n- **Parameters**:\n - `repoUrl`: The URL of the GitHub repository\n - `path`: The file path to fetch (e.g., \"src/index.js\")\n\n### Usage Examples\n\nHere are some examples of how to use these tools with an AI assistant:\n\n1. **Browsing a repository root**:\n Ask your AI assistant to \"Show me the contents of the repository at https://github.com/Ryan0204/github-repo-mcp\"\n\n2. **Exploring a specific directory**:\n Ask \"What files are in the src directory of https://github.com/Ryan0204/github-repo-mcp?\"\n\n3. **Viewing a file**:\n Ask \"Show me the README.md file from https://github.com/Ryan0204/github-repo-mcp\"\n\n### Limitations\n\n- **Rate Limiting**: Without authentication, GitHub API has strict rate limits (60 requests per hour)\n- **Private Repositories**: Can only access public repositories unless a token with appropriate permissions is provided\n- **Binary Files**: The server detects common binary file extensions and won't display their contents\n- **Large Files**: GitHub API has limitations on the size of files that can be retrieved\n\n## Troubleshooting\n\nHere are some common issues and their solutions:\n\n- **Rate limit exceeded**: Set up a GitHub token as described in the Configuration section\n- **Command not found**: Ensure the package is installed globally\n- **Connection errors**: Check your internet connection and GitHub API status\n\nIf you encounter any issues, please check the output for error messages or create an issue in the GitHub repository.\n\n---\n\nEnjoy! βΊοΈ ","readmeFilename":"README.md"}