# mcp-github

MCP server for the GitHub REST API — repos, PRs, issues, branches, commits, reviews, and code search.

## Usage

```bash
bun run src/mcp/cli.ts --stdio     # stdio mode (for MCP integration)
bun run src/mcp/cli.ts --port 3845 # HTTP mode
```

## Add to your MCP host

Wire the server into an MCP host (Claude Code, Cursor, …) by adding it to your `.mcp.json` (or run `claude mcp add`), launching it from your local clone:

```json
{ "mcpServers": { "github": { "command": "bun", "args": ["run", "/abs/path/to/mcp-github/src/mcp/cli.ts", "--stdio"], "env": { "GITHUB_TOKEN": "ghp_..." } } } }
```

> npm package coming soon — run from source for now.

## Env Vars

| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_TOKEN` | Yes | PAT with `repo`, `read:org` scopes |
| `GITHUB_ALLOW_WRITES` | No | Set `true` to enable PRs, reviews, comments, issues |
| `GITHUB_ALLOW_DESTRUCTIVE` | No | Set `true` to also enable merge operations |
| `MCP_CACHE_DIR` | No | Cache directory (default: `.mcp-github/cache`) |

## Tools

**Read-only (always available):**
- `GET /github/repos` — List repos for user or org
- `GET /github/repos/:owner/:repo` — Get repo details
- `GET /github/repos/:owner/:repo/pulls` — List PRs
- `GET /github/repos/:owner/:repo/pulls/:number` — Get PR details
- `GET /github/repos/:owner/:repo/issues` — List issues
- `GET /github/repos/:owner/:repo/branches` — List branches
- `GET /github/repos/:owner/:repo/commits` — List commits
- `GET /github/search/code` — Search code
- `GET /github/search/issues` — Search issues/PRs

**Write (requires `GITHUB_ALLOW_WRITES=true`):**
- `POST /github/repos/:owner/:repo/pulls` — Create PR
- `POST /github/repos/:owner/:repo/pulls/:number/reviews` — Submit review
- `POST /github/repos/:owner/:repo/issues` — Create issue
- `POST /github/repos/:owner/:repo/issues/:number/comments` — Add comment

**Destructive (requires `GITHUB_ALLOW_DESTRUCTIVE=true`):**
- `PUT /github/repos/:owner/:repo/pulls/:number/merge` — Merge PR

## Architecture

Built on `edge.libx.js` RouterWrapper + `describeMCP`. Read-only by default with explicit opt-in for writes. Results spooled to disk via `spool()`.