Content
# Code_Scout_MCP (MCP Tool)
Ask questions about any GitHub repo in plain English — right inside Claude Desktop.
This tool connects to Claude Desktop using **MCP (Model Context Protocol)**. It reads an entire GitHub repository's code, and lets you ask Claude questions about it — like "what does this function do?" or "how is authentication handled in this project?" — and Claude answers using the actual code as context.
---
## What you need before starting
1. **Claude Desktop app** installed ([download here](https://claude.ai/download))
2. **Python 3.10+** installed → check with:
```bash
python --version
```
If not installed, get it from [python.org](https://www.python.org/downloads/) — on Windows, tick "Add Python to PATH" during install.
3. **A GitHub Personal Access Token** (only needed for private repos or to avoid rate limits — public repos work without one too)
- Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token
- Give it `repo` read access only (don't grant more than you need)
---
## Step 1 — Download this project
```bash
git clone https://github.com/YOUR-USERNAME/Code_Scout_MCP.git
cd github-repo-reader
```
(Or click "Code → Download ZIP" on GitHub and extract it if you don't use git.)
## Step 2 — Install the required packages
```bash
pip install -r requirements.txt
```
## Step 3 — Set your GitHub token (optional but recommended)
```
GITHUB_TOKEN=your_token_here
```
> ⚠️ Never share this file or commit it to GitHub. It's already excluded via `.gitignore`.
## Step 4 — Connect it to Claude Desktop
Open your Claude Desktop config file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
Add this entry (edit the path to match where you downloaded the project):
```json
{
"mcpServers": {
"github-repo-reader": {
"command": "python",
"args": ["FULL_PATH_TO/server.py"],
"env": {
"GITHUB_TOKEN": "your_token_here"
}
}
}
}
```
**Tip:** If `python` alone doesn't work, use the full path instead (find it by running `where python` on Windows or `which python3` on Mac/Linux).
## Step 5 — Restart Claude Desktop completely
Don't just close the window — quit it fully from the system tray/menu bar, then reopen it. This is required for Claude to pick up the new tool.
## Step 6 — Try it out
In Claude Desktop, try asking:
> "Read the repo at github.com/some-user/some-project and tell me what it does."
If it's working, Claude will pull in the code and answer using it.
---
## Troubleshooting
| Problem | Likely fix |
|---|---|
| Tool doesn't show up in Claude | Config file has a JSON syntax error — check every comma/bracket. Also confirm you fully restarted Claude. |
| "Command not found" errors | Use the full path to `python.exe` / `python3` instead of just `python` in the config. |
| Rate limit errors from GitHub | Add a `GITHUB_TOKEN` — unauthenticated requests are limited to 60/hour. |
| Still stuck | Check the logs at `%APPDATA%\Claude\logs\mcp-server-github-repo-reader.log` (Windows) for the exact error. |
---
## How it works (short version)
1. Claude Desktop starts this Python script as a background process when you launch the app.
2. When you ask a question, Claude calls this tool, which fetches the relevant files from the GitHub repo using the GitHub API.
3. The code content is passed back to Claude as context, and Claude answers your question using it — like RAG, but over a live repo instead of a static document store.
---
## Contributing
Pull requests welcome! This is a beginner-friendly project, so please keep changes simple and well-commented.
## License
MIT — free to use, modify, and share.
