GitHub_MCP_Server

AriesBerries/GitHub_MCP_Server

3.1

If you are the rightful owner of GitHub_MCP_Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The GitHub MCP Server is a specialized server designed to facilitate communication and data exchange using the Model Context Protocol (MCP).

GitHub MCP Server

A Model Context Protocol (MCP) server for GitHub operations with Human-In-The-Loop (HITL) workflow for Claude Desktop.

Features

  • Read-Only Operations: List organization repositories
  • Mutation Operations: Create branches with two-phase HITL confirmation
  • Security: Organization and repository allowlists, PIN-based confirmation
  • Error Handling: Comprehensive error normalization with consistent error codes
  • Logging: Structured logging with configurable levels and service tags
  • Proposal Management: Time-based expiry with state validation

Architecture

Human-In-The-Loop (HITL) Workflow

Mutation operations follow a two-phase workflow:

  1. Propose Phase: Create a proposal with validation, receive a PIN
  2. Confirm Phase: Execute the operation with PIN validation

This prevents accidental mutations and provides clear audit trails.

Components

  • MCP Server: stdio transport for Claude Desktop integration
  • GitHub Client: API client for GitHub operations (refs-based branch creation)
  • Proposal Store: Manages HITL proposals with expiry and state validation
  • Allowlist: Organization and repository access control
  • Error Handler: Normalized error codes and safe logging
  • Logger: Structured JSON logging with level filtering

Installation

npm install
npm run build

Configuration

Copy .env.example to .env and configure:

# GitHub Personal Access Token (required)
GITHUB_TOKEN=ghp_your_token_here

# Allowed organizations (comma-separated, optional)
ALLOWED_ORGS=myorg,anotherorg

# Allowed repositories (comma-separated, format: owner/repo, optional)
ALLOWED_REPOS=myorg/repo1,myorg/repo2

# HITL proposal TTL in seconds (default: 300)
HITL_PROPOSAL_TTL_SEC=300

# Logging level (DEBUG, INFO, WARN, ERROR)
LOG_LEVEL=INFO

# Service name for logging
SERVICE_NAME=github-mcp-server

Usage

Running the Server

npm start

Or in development mode with watch:

npm run dev

Available Tools

health

Health check endpoint.

Input: None

Output:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0",
  "service": "github-mcp-server"
}
listOrgRepos

List repositories for a GitHub organization (read-only).

Input:

{
  "org": "myorg",
  "page": 1,
  "perPage": 30
}

Output:

{
  "success": true,
  "repositories": [...]
}
createBranch.propose

Propose creating a new branch (HITL phase 1).

Input:

{
  "owner": "myorg",
  "repo": "myrepo",
  "branch": "feature-branch",
  "baseBranch": "main"
}

Output:

{
  "success": true,
  "proposalId": "uuid",
  "pin": "123456",
  "expiresAt": "2024-01-01T00:05:00.000Z",
  "message": "Proposal created. Use PIN 123456 to confirm within 300 seconds."
}
createBranch.confirm

Confirm and execute branch creation (HITL phase 2).

Input:

{
  "proposalId": "uuid",
  "pin": "123456"
}

Output:

{
  "success": true,
  "branch": "feature-branch",
  "sha": "abc123...",
  "url": "https://api.github.com/repos/owner/repo/git/refs/heads/feature-branch",
  "durationMs": 234
}

Development

Building

npm run build

Testing

npm test

Watch mode:

npm run test:watch

Linting

npm run lint
npm run lint:fix

Formatting

npm run format
npm run format:check

Security

  • Secrets are never logged (automatic redaction)
  • Allowlists prevent unauthorized access
  • PIN-based confirmation for mutations
  • Time-limited proposals prevent replay attacks
  • See for more details

Contributing

See for contribution guidelines.

License

MIT