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 — 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:

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:

{
  "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:

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!