GitHub Repo MCP

1# GitHub Repo MCP
2 
3[![smithery badge](https://smithery.ai/badge/@Ryan0204/github-repo-mcp)](https://smithery.ai/server/@Ryan0204/github-repo-mcp)
4 
5<p class="center-text">
6  <strong>GitHub Repo MCP is an open-source MCP server that lets your AI assistants browse GitHub repositories, explore directories, and view file contents.</strong>
7</p>
8 
9<a href="https://glama.ai/mcp/servers/@Ryan0204/github-repo-mcp">
10  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Ryan0204/github-repo-mcp/badge" alt="github-repo-mcp MCP server" />
11</a>
12 
13## Table of contents
14 
15<p class="center-text">
16  <a href="#getting-started">Getting started</a> •
17  <a href="#feature-overview">Feature overview</a>
18</p>
19 
20## ✨ Key features
21 
22- 💻 Compatible with Cursor, Windsurf, Claude Desktop, and other MCP clients supporting `stdio` protocol
23- 🔎 Browse the contents of any public GitHub repository
24- 📂 Navigate through repository directories and subdirectories
25- 📝 View the content of code and text files
26- 📦 Easy installation via package manager
27 
28## Getting Started
29 
30### Prerequisites
31 
32Installing the server requires the following on your system:
33- Node.js 18+
34- npm or yarn
35 
36### Step 1. Installation
37 
38You can install and run GitHub Repo MCP using Smithery, NPX, or setting in mcp.json of your IDE:
39 
40#### MacOS
41 
42```bash
43npx github-repo-mcp
44```
45 
46#### Windows NPX
47 
48```bash
49cmd /c npx -y github-repo-mcp
50```
51 
52#### Windows NPX via .cursor/mcp.json
53 
54```json
55{
56  "mcpServers": {
57    "github-repo-mcp": {
58      "command": "wsl",
59      "args": [
60        "bash",
61        "-c",
62        "cmd /c npx -y github-repo-mcp"
63      ],
64      "enabled": true
65    }
66  }
67}
68```
69 
70#### Windows NPX via .cursor/mcp.json (if path not set)
71 
72```bash
73# Find the full path to npx first
74which npx
75```
76 
77```json
78{
79  "mcpServers": {
80    "github-repo-mcp": {
81      "command": "wsl",
82      "args": [
83        "bash",
84        "-c",
85        "'/home/[username]/.nvm/versions/node/v20.18.0/bin/npx github-repo-mcp'"
86      ],
87      "enabled": true
88    }
89  }
90}
91```
92 
93#### Installing via Smithery
94 
95To install GitHub Repo MCP for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@Ryan0204/github-repo-mcp):
96 
97```bash
98npx -y @smithery/cli install @Ryan0204/github-repo-mcp --client claude
99```
100 
101 
102Wait 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.
103 
104### Step 2. Configuration
105 
106The GitHub Repo MCP server can use a GitHub token for higher rate limits when accessing the GitHub API.
107 
108#### Environment Variables
109 
110| Variable | Required | Default | Description |
111|----------|----------|---------|-------------|
112| `GITHUB_TOKEN` | No | None | Your GitHub personal access token for higher rate limits |
113 
114#### Setting Up a GitHub Token (Optional)
115 
116While the server works without authentication, GitHub API has rate limits that are much lower for unauthenticated requests. To increase your rate limit:
117 
1181. Create a personal access token at https://github.com/settings/tokens
1192. Set the token as an environment variable in mcp.json:
120 
121```json
122{
123  "mcpServers": {
124    "github-repo-mcp": {
125      "command": "...",
126      "args": [
127        ...
128      ],
129      "env": {
130        "GITHUB_TOKEN": "Your_Github_Token"
131      }
132      "enabled": true,
133    }
134  }
135}
136```
137 
138## Feature Overview
139 
140### Repository Browsing Tools
141 
142The server provides three main tools for interacting with GitHub repositories:
143 
144#### 1. `getRepoAllDirectories`
145 
146Lists all files and directories at the root of a GitHub repository.
147 
148- **Parameters**:
149  - `repoUrl`: The URL of the GitHub repository (e.g., "https://github.com/owner/repo")
150 
151#### 2. `getRepoDirectories`
152 
153Lists contents of a specific directory in a GitHub repository.
154 
155- **Parameters**:
156  - `repoUrl`: The URL of the GitHub repository
157  - `path`: The directory path to fetch (e.g., "src")
158 
159#### 3. `getRepoFile`
160 
161Retrieves and displays the content of a specific file from a GitHub repository.
162 
163- **Parameters**:
164  - `repoUrl`: The URL of the GitHub repository
165  - `path`: The file path to fetch (e.g., "src/index.js")
166 
167### Usage Examples
168 
169Here are some examples of how to use these tools with an AI assistant:
170 
1711. **Browsing a repository root**:
172   Ask your AI assistant to "Show me the contents of the repository at https://github.com/Ryan0204/github-repo-mcp"
173 
1742. **Exploring a specific directory**:
175   Ask "What files are in the src directory of https://github.com/Ryan0204/github-repo-mcp?"
176 
1773. **Viewing a file**:
178   Ask "Show me the README.md file from https://github.com/Ryan0204/github-repo-mcp"
179 
180### Limitations
181 
182- **Rate Limiting**: Without authentication, GitHub API has strict rate limits (60 requests per hour)
183- **Private Repositories**: Can only access public repositories unless a token with appropriate permissions is provided
184- **Binary Files**: The server detects common binary file extensions and won't display their contents
185- **Large Files**: GitHub API has limitations on the size of files that can be retrieved
186 
187## Troubleshooting
188 
189Here are some common issues and their solutions:
190 
191- **Rate limit exceeded**: Set up a GitHub token as described in the Configuration section
192- **Command not found**: Ensure the package is installed globally
193- **Connection errors**: Check your internet connection and GitHub API status
194 
195If you encounter any issues, please check the output for error messages or create an issue in the GitHub repository.
196 
197---
198 
199Enjoy! ☺️ 
200