# GitHub MCP Server (Node + TypeScript)

Docker-friendly Model Context Protocol server that lets Codex create and manage GitHub repositories with a single personal access token (PAT).

## Features

- `create_repository`: create a repo under the authenticated user or a given org.
- `upsert_file`: create/update files with commit messages on a branch.
- `create_branch`: branch off any ref (defaults from `main`).
- `whoami`: show the PAT identity.

## Requirements

- Node 20+ (or Docker).
- GitHub PAT in `GITHUB_TOKEN` with at least `repo` scope (or `public_repo` if you only touch public repos).
- For org repos, ensure the token can create repos in that org and that SSO/org policies allow it.

## Local dev

```bash
npm install
npm run dev
```

## Docker build and run

```bash
docker build -t github-mcp .
docker run -i --rm -e GITHUB_TOKEN=... github-mcp
```

## Wire up to Codex (VS Code)

The server speaks MCP over stdio. Configure Codex to start it with:

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "github-mcp"]
    }
  }
}
```

```toml
[mcp_servers.github-mcp]
command = "docker"
args = ["run", "-i", "--rm", "--env-file", "pathToEnv", "github-mcp"]
```

Important: use `"-e", "GITHUB_TOKEN"` (without `=${GITHUB_TOKEN}`) when the command is launched directly (non-shell), so Docker forwards the host `GITHUB_TOKEN` value correctly.

## Notes and safety

- The server uses your PAT directly; treat it like a password.
- Actions are direct commits; there is no local clone.
- If you need organization SAML, approve the PAT for that org first.

## Extending

- Add tools via `server.tool(name, { description, inputSchema }, handler)` in `src/index.ts`.