Content
# GitHub Issues MCP Server
An MCP (Model Context Protocol) server for discovering and triaging open-source GitHub issues — built by hand, connected to Claude Desktop, and used to find good-fit issues to contribute to (SGLang, vLLM, and beyond).
## Features
- **`fetch_issue(repo, issue_number)`** — Get details of a single issue: title, body, state, comments, labels, and whether it's a PR.
- **`list_issues(repo, state, labels, sort, direction, include_prs)`** — Fetch and filter a repo's issues by state, labels, and sort order (up to 100 per call).
- **`find_related_prs(repo, issue_number)`** — Checks an issue's timeline for linked pull requests, and reports whether any are open or merged.
## Setup
1. Install dependencies:
```bash
pip install -r requirements.txt
```
2. Create a `.env` file in the project root:
```
GITHUB_TOKEN=your_personal_access_token
```
Generate a token at GitHub → Settings → Developer settings → Personal access tokens (read-only, `public_repo` scope is enough).
3. Test locally with the MCP inspector:
```bash
mcp dev server.py
```
## Connecting to Claude Desktop
Add the server to Claude Desktop's MCP config (Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"github-issues": {
"command": "uv",
"args": ["run", "--with", "mcp", "mcp", "run", "/absolute/path/to/server.py"]
}
}
}
```
Fully quit and reopen Claude Desktop. Once connected, you can ask things like:
> "Find open good first issues in sgl-project/sglang"
and Claude will call the tools directly and return live results.
## Project Structure
```
├── server.py # MCP server entry point, tool registration
├── github_client.py # GitHub API wrapper (auth, requests, error handling)
├── tools/
│ ├── fetch_issue.py
│ ├── list_issues.py
│ └── find_related_prs.py
└── requirements.txt
```
## Notes
- Uses the GitHub REST API with a personal access token (free, 5,000 requests/hour authenticated).
- Rate limiting and deep error handling are intentionally out of scope for this version — basic status code checks only (200 / 404 / 401 / other).
- `find_related_prs` relies on the issue timeline endpoint's `cross-referenced` events; issues closed manually (without a linked PR) will correctly show no linked PR.
## License
MIT
