Content
# onprem-gh-cli-mcp-server
This is a stdio MCP server for securely using GitHub CLI (`gh`) installed on a local PC from an MCP client. It utilizes local `gh auth` authentication without passing API credentials to the MCP client.
> [!IMPORTANT]
> Currently in Phase 2a. In addition to read operations, it provides creation, update, and commenting of issues using typed tools. Destruction and management operations such as repository deletion, PR merge, and secret changes are not implemented.
## Tool List
### Read
- `get_auth_status`: Check authentication status without displaying tokens
- `list_organizations`: List of organizations visible to the authenticated user
- `list_repositories`: List of repositories
- `list_issues`: List of issues
- `list_pull_requests`: List of pull requests
- `list_workflow_runs`: List of GitHub Actions executions
- `run_gh`: Allowed read-only `gh` commands
### Issue Writing
- `create_issue`: Create an issue
- `update_issue`: Update issue title, body, and open/closed status
- `comment_issue`: Add a comment to an issue
Issue bodies and comments are passed as JSON via standard input using `gh api --input -`, and writing operations are limited to typed tools only, while `run_gh` remains read-only.
## Requirements
- Node.js 20 or higher
- GitHub CLI
- `gh auth login` completed in advance
Issue writing requires GitHub CLI authentication with write permissions to the target repository.
## Startup
After publication, a reviewed version is fixed and started.
```powershell
npx.cmd --yes --prefer-offline @ma-nakaya/onprem-gh-cli-mcp@0.1.0
```
During local development:
```powershell
npm install
npm run build
node dist/cli.js
```
## Configuration
| Variable | Default Value | Description |
|---|---|---|
| `GH_MCP_GH_PATH` | Windows: `gh.exe` | Fixed path of GitHub CLI |
| `GH_MCP_ALLOWED_HOSTS` | `github.com` | Allowed hosts (comma-separated) |
| `GH_MCP_ALLOWED_OWNERS` | No restrictions | Allowed owners/organizations |
| `GH_MCP_ALLOWED_REPOSITORIES` | No restrictions | Allowed repositories (`owner/name`) |
| `GH_MCP_TIMEOUT_MS` | `30000` | Command timeout |
| `GH_MCP_MAX_OUTPUT_BYTES` | `1000000` | Maximum output size |
| `GH_MCP_AUDIT_LOG_PATH` | OS-specific user area | Fixed path of JSONL audit log |
Default audit log path:
- Windows: `%LOCALAPPDATA%\onprem-gh-cli-mcp\audit.jsonl`
- Linux/macOS: `$XDG_STATE_HOME/onprem-gh-cli-mcp/audit.jsonl`, or `~/.local/state/onprem-gh-cli-mcp/audit.jsonl` if not set
Please set `GH_MCP_ALLOWED_OWNERS` or `GH_MCP_ALLOWED_REPOSITORIES` when using in production. The audit log path cannot be changed from the MCP tool input and is fixed with environment variables or default values.
## Audit Log
Records issue writing start and completion in JSON Lines format.
Recorded items:
- timestamp
- tool
- hostname
- repository
- issueNumber (if applicable)
- outcome (`started` / `succeeded` / `failed`)
- durationMs
The following information is not recorded:
- Issue title
- Issue body
- Comment body
- Token, Secret
- Full standard output and standard error of GitHub CLI
If the start record cannot be written, the write operation is not executed. If writing the completion record fails, `audit.completed` in the MCP response will be `false`.
## Secure MCP Tunnel Configuration Example
```yaml
mcp:
transport: stdio
command: npx.cmd
args:
- --yes
- --prefer-offline
- "@ma-nakaya/onprem-gh-cli-mcp@0.1.0"
```
## Security
- Launch `gh.exe` directly with `shell: false`
- Reject `gh auth token` and `--show-token`
- Reject write subcommands in `run_gh`
- Limit writing operations to dedicated tools with input schema only
- Pass issue bodies and comments via standard input, not process arguments
- Limit environment variables passed to child processes
- Mask GitHub Token-like output
- Limit execution time and output size
- Support repository/owner/host allowlists
- Do not save issue bodies, comments, tokens, and secrets in audit logs
## Current Implementation Scope
- Phase 1: Foundation, reading, organization list, allowlist, CI, and actual machine confirmation
- Phase 2a: Issue creation, update, commenting, and JSONL audit log
- Not implemented: PR and release creation, workflow dispatch, project, deletion, PR merge, secret, and two-factor authentication
## Development
```powershell
npm install
npm run check
npm test
npm run build
```
## License
MIT
