# GitHub Repo Manager MCP

This MCP server lets an AI client manage GitHub repositories through the GitHub REST and GraphQL APIs.

## What This MCP Tool Can Do

- Create new repositories
- Update repo details, including description, homepage, topics/tags, and visibility
- Delete repositories
- Add topics/labels to repos for organization
- List all repos with filters
- Rename repositories
- Archive old repos
- Pin repositories via the GitHub GraphQL API
- Read file contents from repositories
- Create or update files in repositories, such as `README.md`

## Security Note

Never hard-code a GitHub token in source files. Set it as an environment variable named `GITHUB_TOKEN`.

If you pasted a real token into chat or committed it anywhere, revoke it in GitHub and create a new token.

## Setup

```bash
npm install
```

Create a `.env` file in this project folder:

```bash
GITHUB_TOKEN=github_pat_your_token_here
```

The token needs permissions for the operations you want to use. For fine-grained personal access tokens, grant repository administration, contents, and metadata access for the target repositories.

Classic PAT notes:

- Deleting repositories requires the `delete_repo` scope.
- Updating repository files requires repo contents write access.
- Pinning repositories uses GitHub GraphQL `addPinnedItem`; use a token that can access the target repository and update the authenticated user's pinned items.

## Run

```bash
npm start
```

## Install From npm

After this package is published, users can run it without cloning the repo:

```bash
npx github-repo-manager-mcp
```

Or install it globally:

```bash
npm install -g github-repo-manager-mcp
github-repo-manager-mcp
```

Set `GITHUB_TOKEN` in your MCP client environment. If you clone this repository locally, the server can also load `GITHUB_TOKEN` from a `.env` file in the project folder.

## MCP Client Config

Example client config using `npx`:

```json
{
  "mcpServers": {
    "github-repo-manager": {
      "command": "npx",
      "args": ["-y", "github-repo-manager-mcp"],
      "env": {
        "GITHUB_TOKEN": "github_pat_your_token_here"
      }
    }
  }
}
```

Example local development config:

```json
{
  "mcpServers": {
    "github-repo-manager": {
      "command": "C:/PROGRA~1/nodejs/node.exe",
      "args": ["C:/Users/msaad/OneDrive/Documents/github_organized/src/server.js"],
      "env": {
        "GITHUB_TOKEN": "github_pat_your_token_here"
      }
    }
  }
}
```

The server also loads `GITHUB_TOKEN` from the local `.env` file automatically, so the `env` block is optional if `.env` is present.

## Publish to npm

Before publishing, make sure you are logged in:

```bash
npm login
```

Then publish:

```bash
npm publish --access public
```

The package publishes only `src`, `README.md`, `LICENSE`, and `run-mcp.cmd`.

## MCP Inspector on Windows

Use these settings in MCP Inspector:

**Transport Type**

```text
STDIO
```

**Command**

```text
C:\PROGRA~1\nodejs\node.exe
```

**Arguments**

```text
C:/Users/msaad/OneDrive/Documents/github_organized/src/server.js
```

Use the short Node path to avoid the space in `Program Files`. Use forward slashes in the server path because MCP Inspector can strip backslashes from Windows paths in the Arguments field.

## Available Tools

- `create_repository`: Create a repository for the authenticated user or an organization. Supports description, homepage, privacy, auto-init, `.gitignore`, license, and topics.
- `update_repository`: Update description, homepage, visibility/privacy, feature flags, default branch, archived state, and topics.
- `delete_repository`: Delete a repository. Requires `confirm=true`.
- `add_repository_topics`: Add topics without removing existing topics.
- `add_repository_labels`: Create labels, or update existing labels if they already exist.
- `list_repositories`: List repositories visible to the authenticated user, an owner, or an organization with filters for visibility, archived state, topic, name, sort, and direction.
- `rename_repository`: Rename a repository.
- `archive_repository`: Archive a repository.
- `pin_repository`: Pin a repository to the authenticated user's GitHub profile via GraphQL.
- `get_file_content`: Read a file from a repository, defaulting to `README.md`.
- `update_file_content`: Create or update a file in a repository, defaulting to `README.md`; it auto-fetches the current SHA when updating an existing file.

## Tool Inputs

Most tools accept an optional `owner`. If omitted, the server uses the authenticated GitHub user's login.

`get_file_content` inputs:

```json
{
  "owner": "optional-owner",
  "repo": "repo-name",
  "path": "README.md",
  "branch": "optional-branch"
}
```

`update_file_content` inputs:

```json
{
  "owner": "optional-owner",
  "repo": "repo-name",
  "path": "README.md",
  "content": "# New content",
  "message": "Update README via MCP",
  "branch": "optional-branch"
}
```

To update an existing file, `sha` is optional because the server attempts to fetch it automatically.