# GitHub Context MCP Server

An MCP (Model Context Protocol) server that gives Claude access to one or more GitHub repositories — including private ones — directly from Claude Desktop or Claude Code.

Repositories are managed **dynamically at runtime**: just tell Claude to add or remove a repo and it's persisted immediately, with no config file editing required.

## Prerequisites

- [Node.js](https://nodejs.org/) 18 or later
- A [GitHub Personal Access Token](https://github.com/settings/tokens)

## Installation

```bash
npm install
npm run build
```

## GitHub Token Setup

1. Go to **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)**
2. Click **Generate new token (classic)**
3. Give it a name (e.g. `claude-mcp`)
4. Select the **`repo`** scope (covers both public and private repositories)
5. Click **Generate token** and copy it

> If you only need public repos, the `public_repo` scope is sufficient.

## Claude Desktop Configuration

Edit the config file at:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Add this block inside `"mcpServers"`:

```json
{
  "mcpServers": {
    "github-context": {
      "command": "node",
      "args": ["path_to_repo/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

That's it — no repo list needed here. Restart Claude Desktop after saving.

## Managing repositories

Repos are managed through Claude itself at runtime. The list is stored in `dist/repos.json` and persists across sessions.

### Add a repo

> "Add the repo myorg/backend to GitHub context"

Claude calls `add_repo` → verifies the repo is accessible with your token → saves it to `repos.json`.

### Remove a repo

> "Remove myorg/old-project from GitHub context"

Claude calls `remove_repo` → updates `repos.json`.

### List current repos

> "What repos do you have access to?"

Claude calls `list_repos` → shows everything currently saved.

---

Changes take effect immediately — no restart needed.

## Available Tools

### Repo management

| Tool | Description |
|---|---|
| `list_repos` | Show all saved repositories |
| `add_repo` | Add a repo (verifies access before saving) |
| `remove_repo` | Remove a repo from the list |

### Data access

| Tool | Description |
|---|---|
| `get_repo_info` | Metadata: description, language, stars, default branch, visibility |
| `list_files` | Browse files and directories at any path |
| `get_file` | Read the full content of any file |
| `search_code` | Search code across a repo (GitHub search API) |
| `get_commits` | Recent commit history, optionally filtered by branch or file path |
| `get_branches` | List all branches (protected branches are marked) |
| `get_pull_requests` | List open, closed, or all pull requests |
| `get_issues` | List open, closed, or all issues |

### Common parameters

- **`repo`** — `"owner/repo"` format, must be in the saved list
- **`branch`** — branch name, tag, or commit SHA (defaults to the repo's default branch)
- **`path`** — file or directory path inside the repo
- **`max_results`** — how many items to return
- **`state`** — `"open"`, `"closed"`, or `"all"` (for PRs and issues)

## Example prompts

```
Add the repo myorg/backend to GitHub context.

List all the files in the src/ directory of myorg/backend.

Read the file src/auth/middleware.ts from myorg/backend.

Search for "function authenticate" in myorg/backend.

Show me the last 10 commits on the main branch of myorg/frontend.

What open issues are there in myorg/backend?

Remove myorg/old-project from GitHub context.
```

## Repos file location

By default repos are stored at `dist/repos.json` next to the built script. To use a custom path, set the `REPOS_FILE` env var in your Claude Desktop config:

```json
"env": {
  "GITHUB_TOKEN": "ghp_your_token_here",
  "REPOS_FILE": "localpath/.config/github-mcp/repos.json"
}
```

This is useful if you want the repo list to survive rebuilds or to share it across multiple projects.

## Development

Run without building (useful for local testing):

```bash
GITHUB_TOKEN=ghp_... npm run dev
```

Recompile after making source changes:

```bash
npm run build
```

Then restart Claude Desktop.

## Project structure

```
├── src/
│   └── index.ts          # MCP server — all tools, repo persistence logic
├── dist/                 # Compiled output (generated by npm run build)
│   ├── index.js
│   └── repos.json        # Persisted repo list (auto-created on first add_repo)
├── package.json
├── tsconfig.json
├── .env.example
└── claude-desktop-config.example.json
```

## Security notes

- Your GitHub token is passed via environment variable and never logged or sent to Claude.
- Only repos explicitly added via `add_repo` are accessible — Claude cannot reach other repos even if your token has broader access.
- `add_repo` verifies the repo exists and is accessible with your token before saving it.
- File content is truncated at 100,000 characters to prevent context overflow.