github-mcp-server

github-mcp-server

A minimal MCP server for GitHub in ~140 lines of Python. Browse repos, read code, search, and get insights — all through natural language via Claude, Cursor, or any MCP client.

Tools

| Tool | Description | |------|-------------| | list_repos | List repositories with language, stars, and last update | | get_repo_structure | View the file tree of any repo | | get_file | Read any file's content | | search_code | Search code across your repos | | list_issues | Get open/closed issues | | get_commits | Recent commit history | | repo_stats | Languages breakdown, stars, forks, dates |

Quick Start

# Clone
git clone https://github.com/ArnabbLank/github-mcp-server.git
cd github-mcp-server

# Install
pip install -e .

# Configure
cp .env.example .env
# Edit .env with your GitHub token (Settings → Developer settings → Personal access tokens)

# Run
mcp dev server.py

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["/path/to/github-mcp-server/server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token",
        "GITHUB_OWNER": "your_username"
      }
    }
  }
}

Restart Claude Desktop. You can now ask things like:

• "Show me my recent repos"
• "Read the README from my EnvCraft project"
• "Search for uses of FastAPI across my repos"
• "What issues are open on github-mcp-server?"

How It Works

This server implements the Model Context Protocol using fastmcp. Each tool is a Python function decorated with @mcp.tool() — the MCP client (Claude, Cursor) discovers them automatically and calls them when relevant.

┌─────────────┐       MCP (stdio/SSE)       ┌──────────────┐      HTTPS       ┌────────┐
│ Claude/Cursor│ ◄──────────────────────────► │  server.py   │ ◄──────────────► │ GitHub │
│  (MCP Client)│                              │ (MCP Server) │                  │  API   │
└─────────────┘                               └──────────────┘                  └────────┘

Add Your Own Tool

@mcp.tool()
async def my_tool(repo: str, owner: str = "") -> str:
    """Description shown to the LLM."""
    owner = owner or OWNER
    data = await _get(f"/repos/{owner}/{repo}/whatever")
    return format_data(data)

That's it. The LLM sees the function name, docstring, and parameter types — no extra config needed.

Token Permissions

The GitHub token needs these scopes:

• repo — for private repo access (optional, skip for public-only)
• read:user — for listing repos

Generate one at: https://github.com/settings/tokens

License

MIT