# GitHub MCP Server

FastMCP server for GitHub pull requests, code, and reviews.

## Features

- Repository/account helpers: authenticated user, repository metadata, branches, branch creation, ref comparison.
- Pull requests: list, get, create, update, merge, changed files, commits, raw diff.
- Code: read files, list directories, search code, create/update text files, delete files.
- Reviews: list reviews, list review comments, list conversation comments, add conversation comments, create/submit/dismiss reviews, add file-level review comments, request reviewers.

## Create `.env` file

```
GITHUB_TOKEN=github_pat_or_personal_access_token_here
GITHUB_OWNER=owner-or-org
GITHUB_REPO=repo-name

# Optional
GITHUB_API_URL=https://api.github.com
GITHUB_API_VERSION=2022-11-28
```

`GITHUB_OWNER` and `GITHUB_REPO` are optional if every tool call passes `owner` and `repo`.

For fine-grained GitHub tokens, grant only the permissions you need. Common permissions:

- Pull requests: read/write
- Contents: read/write
- Metadata: read
- Issues: read/write, for pull request conversation comments

## Create a virtual environment

```
cd PROJECT_FOLDER
python3 -m venv .venv
```

## Activate it

```
source .venv/bin/activate
```

## Install dependencies

```
pip install fastmcp requests python-dotenv
```

## Freeze the requirements

```
pip freeze > requirements.txt
```

## Test it

```
python3 server.py
```

You should see:

`Starting MCP server 'github-mcp-server' with transport 'stdio'`

## Configure OpenCode

```
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": [
        "PATH_TO_YOUR_MCP_PROJECT/.venv/bin/python",
        "PATH_TO_YOUR_MCP_PROJECT/server.py"
      ],
      "enabled": true
    }
  }
}
```

## Docker / HTTP mode

```
docker compose up --build
```

HTTP mode listens on port `8002`.

## Useful Next Features

- Issues and labels: create issues, triage labels, milestone assignment, linked PR discovery.
- Checks and CI: list check suites/runs, rerun failed checks, summarize failing annotations.
- Actions workflows: list workflow runs, trigger `workflow_dispatch`, download artifacts.
- Releases and tags: draft releases, generate changelog notes, compare release refs.
- Branch protection: inspect required checks, review rules, and merge restrictions.
- Security: Dependabot alerts, secret scanning alerts, code scanning alerts, SARIF summaries.
- Repository admin: collaborators, teams, permissions, rulesets, webhooks.
- Notifications: list assigned/review-requested items across repositories.
- Project planning: GitHub Projects items, statuses, and field updates.