github-mcp

# github-mcp Hi! This is a small project I built that lets **Claude** look up stuff on **GitHub** for me. So instead of opening a browser to check how many stars a repo has, I just ask Claude and it figures it out. It works using something called **MCP** *(Model Context Protocol)*. MCP is like a USB port for AI: it's a standard way to plug external tools into an AI assistant. This project is one of those tools. ## What can it do? Once it's plugged into Claude, I can ask things like: - "What's on daniel-diyali's GitHub profile?" - "Show me my 5 most recently updated repos." - "Tell me about my github-mcp repo." - "Find the top Python MCP projects." - "What have I been doing on GitHub lately?" Under the hood, I gave Claude 5 tools to work with: 1. **`get_github_user`** — basic profile info (bio, repo count, followers). 2. **`get_github_repos`** — a user's most recently updated repos. 3. **`get_repo_details`** — info on one specific repo. 4. **`search_repos`** — search GitHub by keyword. 5. **`get_user_events`** — what someone's been up to recently. ## What I needed - Python 3.13 or newer - [`uv`](https://docs.astral.sh/uv/) — a fast Python package manager. If I didn't have it: `curl -LsSf https://astral.sh/uv/install.sh | sh` - Claude Desktop — the app that actually runs and talks to my server ## Getting it running ### 1. Install the dependencies From inside the project folder: ```bash uv sync ``` This reads my `pyproject.toml`, creates a virtual environment in `.venv/`, and installs the two libraries I use: `httpx` (for HTTP requests) and `mcp[cli]` (the MCP framework that does most of the heavy lifting). ### 2. Hook it up to Claude Desktop Claude Desktop has a config file where I tell it what MCP servers to run. I open it here: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` If the file doesn't exist yet, I just create it. Then I paste this in: ```json { "mcpServers": { "github-stats": { "command": "uv", "args": [ "--directory", "/Users/danieldiyali/Documents/AI_Projects/github-mcp", "run", "python", "server.py" ] } } } ``` What I learned this config does: - **`command` + `args`**: this is literally the shell command Claude runs to start my server. In English: *"go to my project folder and run `python server.py` using `uv`."* Then I **fully quit and reopen Claude Desktop** (Cmd+Q on Mac, not just closing the window — quitting matters because Claude only re-reads the config on startup). When it comes back, I should see a small tools indicator in the message box. Clicking it shows `github-stats`. ### 3. Try it out I just ask Claude something like: > "What's on daniel-diyali's GitHub profile?" If it works, Claude calls my tool and gives me back the info. 🎉 ## Troubleshooting (stuff I had to figure out) **Claude doesn't show the tool.** Almost always a config file mistake. I check: - The path in `--directory` is the *absolute* path to my project - The JSON is valid (a missing comma silently breaks it — I paste it into <https://jsonlint.com> to verify) - I actually quit Claude (Cmd+Q), not just closed the window When things break, the logs are super useful: ``` ~/Library/Logs/Claude/mcp-server-github-stats.log ``` **It says "User not found" but the user definitely exists.** GitHub usernames are case-sensitive in some places. I copy the exact spelling from the profile URL to be safe. ## Testing it without Claude I can ask the server to list its tools straight from the command line — useful when I've changed the code and want to make sure nothing's broken: ```bash uv run python -c " import asyncio, server async def main(): for t in await server.mcp.list_tools(): print('-', t.name) asyncio.run(main()) " ``` I should see all 5 tool names print. ## What's in this project? ``` github-mcp/ ├── server.py ← the actual MCP server, all 5 tools live here ├── pyproject.toml ← project metadata + dependency list ├── uv.lock ← exact versions of dependencies (auto-generated) ├── .gitignore ← stops me from committing .venv/, secrets, etc. └── README.md ← I'm reading it right now ``` That's it. Have fun!