# 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

```bash
# 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`:

```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](https://modelcontextprotocol.io/) using [`fastmcp`](https://github.com/jlowin/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

```python
@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