Content
<p align="center">
<b>English</b> | <a href="README.fa.md">فارسی</a>
</p>
# github-mcp-lite
A minimal [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server
for creating GitHub repositories, committing files, and publishing releases
using a plain Personal Access Token (PAT).
No Docker, no local Git installation, and no GitHub Copilot subscription
required — unlike the [hosted `api.githubcopilot.com/mcp/`
server](https://github.com/github/github-mcp-server), which gates access
behind a Copilot entitlement. This server talks directly to the regular
GitHub REST API (`api.github.com`) over plain `fetch`, so it's a single
dependency-light file you can read top to bottom in a few minutes.
## Why this exists
Most MCP GitHub integrations either require a full local git toolchain, a
Docker container, or a Copilot-gated hosted endpoint. `github-mcp-lite` is
for cases where you just want an AI assistant to be able to:
- spin up a new repo,
- push a batch of files to it in one commit, and
- tag a release,
using nothing but a token you already have.
## Tools
| Tool | Description | Destructive? |
| --- | --- | --- |
| `get_authenticated_user` | Return the login/profile for the account owning the configured token. | No |
| `create_repository` | Create a repo owned by the authenticated user. Auto-initialized with a README so a default branch exists immediately. | No |
| `commit_files` | Create or update one or more text files in a single commit. | Yes (overwrites file contents) |
| `create_release` | Publish a tagged GitHub release. | No |
| `delete_repository` | Permanently delete a repository. Requires the `delete_repo` token scope. | **Yes, irreversible** |
Each tool is annotated with `readOnlyHint` / `destructiveHint` /
`openWorldHint` metadata so MCP clients can surface appropriate confirmation
prompts.
### `get_authenticated_user`
No input. Returns `{ login, html_url, name }` for the token's owner.
### `create_repository`
| Param | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | yes | Repository name |
| `description` | string | no | Repository description |
| `private` | boolean | no | Defaults to `false` (public) |
Returns `{ full_name, html_url, clone_url, default_branch }`.
### `commit_files`
| Param | Type | Required | Notes |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner |
| `repo` | string | yes | Repository name |
| `branch` | string | no | Defaults to the repo's default branch |
| `message` | string | yes | Commit message |
| `files` | array of `{ path, content }` | yes | UTF-8 text content only; at least one file |
Internally this creates blobs, a tree, and a commit via the Git Data API,
then fast-forwards the branch ref — so it's a real single commit, not one
commit per file. Returns `{ commit_sha, html_url, files_changed }`.
### `create_release`
| Param | Type | Required | Notes |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner |
| `repo` | string | yes | Repository name |
| `tag_name` | string | yes | e.g. `v1.0.0` |
| `name` | string | no | Release title |
| `body` | string | no | Release notes (Markdown) |
| `target_commitish` | string | no | Branch or commit SHA to tag; defaults to the default branch |
| `draft` | boolean | no | Defaults to `false` |
| `prerelease` | boolean | no | Defaults to `false` |
Returns `{ html_url, id, tag_name }`.
### `delete_repository`
| Param | Type | Required | Notes |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner |
| `repo` | string | yes | Repository name |
Permanently deletes the repository. Returns `{ deleted: true, full_name }`.
Requires a classic PAT with the `delete_repo` scope — fine-grained tokens
generally cannot delete repositories.
## Installation
### Prerequisites
- [Node.js](https://nodejs.org/) 18+ (for native `fetch` support)
- A GitHub [Personal Access Token](https://github.com/settings/tokens) with
the `repo` scope (add `delete_repo` too if you want to use
`delete_repository`)
> **Note:** Repository *creation* isn't reliably supported by fine-grained
> PATs, so a **classic** token is recommended.
### Clone and install dependencies
```bash
git clone https://github.com/MatinMHF/github-mcp-lite.git
cd github-mcp-lite
npm install
```
### Configure your token
The server reads the token from either `GITHUB_PERSONAL_ACCESS_TOKEN` or
`GITHUB_TOKEN` in its environment. Set one of these before it starts — the
process exits immediately with an error if neither is present.
## Usage
### Run directly
```bash
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx node index.js
```
The server communicates over stdio, so it's meant to be launched by an MCP
client (Claude Code, Claude Desktop, etc.), not run interactively on its own.
### Register with Claude Code
```bash
claude mcp add github-lite -s user -e GITHUB_PERSONAL_ACCESS_TOKEN=<your_token> -- node /path/to/index.js
```
On Windows PowerShell, quote the separator as `"--"` — PowerShell silently
strips a bare `--` before it reaches the script's arguments, which breaks
argument parsing:
```powershell
claude mcp add github-lite -s user -e GITHUB_PERSONAL_ACCESS_TOKEN=<your_token> "--" node "C:/path/to/index.js"
```
### Register with Claude Desktop (or any MCP-compatible client)
Add an entry to your client's MCP server config (e.g.
`claude_desktop_config.json`):
```json
{
"mcpServers": {
"github-lite": {
"command": "node",
"args": ["C:/path/to/github-mcp-lite/index.js"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
}
}
```
### Example workflow
A typical session once the server is registered with your MCP client:
1. **"Who am I authenticated as?"** → calls `get_authenticated_user`
2. **"Create a public repo called `my-project`"** → calls `create_repository`
(auto-initializes with a README so a default branch exists)
3. **"Commit these files to it"** → calls `commit_files` with an array of
`{ path, content }` entries, written in a single commit
4. **"Publish a v1.0.0 release"** → calls `create_release`
## Security notes
- The token is read once from the environment at startup and never logged.
- `commit_files` and `delete_repository` are marked `destructiveHint: true`
in their tool annotations — well-behaved MCP clients should prompt for
confirmation before invoking them.
- Because this server has `openWorldHint: true` on every tool (it makes
real network calls to `api.github.com`), only run it with a token scoped
to what you actually need.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This project follows a
[Code of Conduct](CODE_OF_CONDUCT.md). To report a security issue, see
[SECURITY.md](SECURITY.md).
## License
MIT
