# github-mcp-lite

A small [Model Context Protocol](https://modelcontextprotocol.io/) server for GitHub — nine tools, PAT auth, stdio transport.

The official [`github/github-mcp-server`](https://github.com/github/github-mcp-server) covers a lot of ground (60+ tools). Handy for org admin and security workflows, but heavy if you mostly read files, scan PRs, and file issues. GitHub's been nudging people toward smaller tool sets for that reason ([changelog](https://github.blog/changelog/2025-12-10-github-mcp-server-tool-specific-configuration/), [notes on token use](https://github.blog/ai-and-ml/github-copilot/improving-token-efficiency-in-github-agentic-workflows/)).

This repo is the opposite end: fixed scope, short tool list, easy to skim before you plug it into an MCP host.

## Install

```bash
git clone https://github.com/benjimkh/github-mcp-lite.git
cd github-mcp-lite
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Run it:

```bash
export GITHUB_TOKEN=ghp_...
github-mcp-lite
```

MCP client config (stdio):

```json
{
  "mcpServers": {
    "github-mcp-lite": {
      "command": "/absolute/path/to/github-mcp-lite/.venv/bin/github-mcp-lite",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

See [`examples/mcp-client.json`](examples/mcp-client.json).

## Tools

| Tool | What it does |
|------|----------------|
| `get_repo` | Metadata, default branch, visibility, star count |
| `search_code` | Code search (`repo:owner/name` queries work well) |
| `get_file_contents` | Read a file or list a directory at a ref |
| `list_pull_requests` | Open / closed / all PRs |
| `get_pull_request` | Single PR with merge state and diff stats |
| `create_issue` | Open a new issue |
| `comment_on_issue` | Comment on an issue or PR thread |
| `list_issues` | Issues only (PRs filtered out) |
| `search_repositories` | Repo search |

No gists, notifications, or org settings — that's intentional.

## Benchmark

Ballpark tool/schema footprint vs the official server:

```bash
python3 benchmark/measure_schema_size.py
```

Background: [`docs/context-budget-guide.md`](docs/context-budget-guide.md).

## This repo vs official github-mcp-server

| github-mcp-lite | official server |
|-----------------|-----------------|
| Few repos, everyday PR/issue work | Org admin, security, Dependabot |
| Short tool list you can read in a minute | Actions, Projects, Discussions, etc. |
| PAT + stdio | Copilot OAuth integration |

## License

MIT — see [LICENSE](LICENSE). PRs welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).