GitHub MCP API Client

A TypeScript package for interacting with the GitHub API through an MCP (Model Context Protocol) server integration.

Features

• Full TypeScript support with type definitions
• 129 MCP tools covering all major GitHub API operations:
  • Repository management (create, update, delete, search, settings, administration)
  • Issue tracking (create, update, close, comments, search)
  • Pull request management (create, merge, review, comments)
  • Branch operations (create, delete, list, protect)
  • Commit operations (list, get, compare)
  • Release management (create, update, delete, assets)
  • Content operations (read, write, delete files)
  • GitHub Actions (workflows, runs, artifacts)
  • Webhooks (create, update, delete, deliveries, redelivery)
  • Collaborators and teams (add, remove, permissions)
  • Repository statistics and insights
  • Security settings (Dependabot, vulnerability alerts)
  • Advanced search across repositories, issues, PRs, code, commits, users, topics, and labels
• Built-in logging with @onamfc/developer-log
• Package inspection with @onamfc/pkg-inspect
• Robust error handling

Installation

From NPM

npm install @onamfc/mcp-github-integration

From Source

git clone https://github.com/onamfc/mcp-github-integration.git
cd mcp-github-integration
npm install
npm run build

Configuration

Set your GitHub personal access token as an environment variable:

export GITHUB_TOKEN=your_github_token_here

Usage

Using the MCP Server

import{MCPServer}from'@onamfc/mcp-github-integration';constserver=newMCPServer(process.env.GITHUB_TOKEN);// Get authenticated userconstresponse=awaitserver.handleRequest({method: 'github_get_authenticated_user',params: {},});if(response.success){console.log('User:',response.data);}// Search repositoriesconstsearchResponse=awaitserver.handleRequest({method: 'github_search_repositories',params: {q: 'typescript',per_page: 10,},});

Using the GitHub Client Directly

import{GitHubClient}from'@onamfc/mcp-github-integration';constclient=newGitHubClient({token: process.env.GITHUB_TOKEN,});// Create a new repositoryconstnewRepo=awaitclient.createRepository({name: 'my-awesome-project',description: 'My awesome project description',private: false,auto_init: true,});// Get repository informationconstrepo=awaitclient.getRepository('owner','repo-name');console.log(repo);// Create an issueconstissue=awaitclient.createIssue({owner: 'owner',repo: 'repo-name',title: 'Bug Report',body: 'Description of the bug',labels: ['bug'],});// List pull requestsconstprs=awaitclient.listPullRequests({owner: 'owner',repo: 'repo-name',state: 'open',});

Available GitHub API Operations

Repository Operations (25 endpoints)

• github_get_repository - Get repository information
• github_list_repositories - List user's public repositories
• github_create_repository - Create a new repository
• github_delete_repository - Delete a repository
• github_update_repository - Update repository settings and configuration
• github_get_repository_topics - Get repository topics/tags
• github_replace_repository_topics - Set repository topics for discoverability
• github_get_repository_languages - Get programming languages used
• github_get_code_frequency_stats - Get weekly addition/deletion statistics
• github_get_contributors_stats - Get contributor activity statistics
• github_get_participation_stats - Get weekly commit count statistics
• github_transfer_repository - Transfer repository to new owner
• github_list_repository_teams - List teams with access to repository
• github_check_team_permission - Check team permission for repository
• github_add_repository_team - Add or update team access to repository
• github_remove_repository_team - Remove team access from repository
• github_enable_automated_security_fixes - Enable Dependabot automated security fixes
• github_disable_automated_security_fixes - Disable automated security fixes
• github_enable_vulnerability_alerts - Enable Dependabot vulnerability alerts
• github_disable_vulnerability_alerts - Disable vulnerability alerts

Collaborator Management (7 endpoints)

• github_list_collaborators - List repository collaborators
• github_check_collaborator - Check if user is a collaborator
• github_add_collaborator - Add collaborator to repository
• github_remove_collaborator - Remove collaborator from repository
• github_get_collaborator_permission - Get collaborator permission level
• github_list_repository_invitations - List pending repository invitations
• github_delete_repository_invitation - Delete/cancel a repository invitation

Issue Operations (9 endpoints)

• github_create_issue - Create a new issue
• github_list_issues - List issues in a repository
• github_get_issue - Get a specific issue
• github_update_issue - Update an existing issue
• github_close_issue - Close an issue
• github_create_issue_comment - Add a comment to an issue
• github_list_issue_comments - List comments on an issue
• github_update_issue_comment - Update an issue comment
• github_delete_issue_comment - Delete an issue comment

Pull Request Operations (4 endpoints)

• github_create_pull_request - Create a new pull request
• github_list_pull_requests - List pull requests in a repository
• github_get_pull_request - Get a specific pull request
• github_merge_pull_request - Merge a pull request

Branch Operations (5 endpoints)

• github_list_branches - List all branches in a repository
• github_get_branch - Get information about a specific branch
• github_create_branch - Create a new branch
• github_delete_branch - Delete a branch
• github_get_branch_protection - Get branch protection rules

Commit Operations (3 endpoints)

• github_list_commits - List commits in a repository
• github_get_commit - Get a specific commit
• github_compare_commits - Compare two commits or branches

Release Operations (6 endpoints)

• github_list_releases - List all releases
• github_get_latest_release - Get the latest release
• github_get_release - Get a specific release by ID
• github_create_release - Create a new release
• github_update_release - Update a release
• github_delete_release - Delete a release

Content Operations (5 endpoints)

• github_get_file_content - Get contents of a file
• github_create_file - Create a file
• github_update_file - Update a file
• github_delete_file - Delete a file
• github_get_directory_content - Get contents of a directory

GitHub Actions (9 endpoints)

• github_list_workflows - List all workflows
• github_get_workflow - Get a specific workflow
• github_list_workflow_runs - List workflow runs
• github_get_workflow_run - Get a specific workflow run
• github_cancel_workflow_run - Cancel a workflow run
• github_rerun_workflow - Re-run a workflow
• github_delete_workflow_run - Delete a workflow run
• github_list_workflow_run_artifacts - List artifacts for a workflow run
• github_download_artifact - Download a workflow artifact

Webhook Operations (11 endpoints)

• github_list_webhooks - List all webhooks for a repository
• github_get_webhook - Get a specific webhook by ID
• github_create_webhook - Create a new webhook
• github_update_webhook - Update an existing webhook
• github_delete_webhook - Delete a webhook
• github_ping_webhook - Trigger a ping event to webhook
• github_test_webhook - Trigger a test push event to webhook
• github_list_webhook_deliveries - List deliveries for a webhook
• github_get_webhook_delivery - Get a specific webhook delivery
• github_redeliver_webhook - Redeliver a webhook delivery

Search Operations (8 endpoints)

• github_search_repositories - Search for repositories
• github_search_issues - Search for issues and pull requests
• github_search_code - Search code across repositories
• github_search_commits - Search commits
• github_search_users - Search for users
• github_search_topics - Search for topics
• github_search_labels - Search for labels in a repository

User Operations (1 endpoint)

• github_get_authenticated_user - Get authenticated user information

Common Use Cases

Repository Automation

Create and configure repositories programmatically:

// Create repository with full configurationawaitserver.handleRequest({method: 'github_create_repository',params: {name: 'my-project',description: 'My awesome project',private: false,auto_init: true,gitignore_template: 'Node',license_template: 'mit',},});// Update repository settingsawaitserver.handleRequest({method: 'github_update_repository',params: {owner: 'myorg',repo: 'my-project',has_issues: true,has_wiki: false,allow_squash_merge: true,delete_branch_on_merge: true,},});// Add topics for discoverabilityawaitserver.handleRequest({method: 'github_replace_repository_topics',params: {owner: 'myorg',repo: 'my-project',topics: ['javascript','api','automation'],},});

Team & Access Management

Manage collaborators and permissions:

// Add collaboratorawaitserver.handleRequest({method: 'github_add_collaborator',params: {owner: 'myorg',repo: 'my-project',username: 'developer123',permission: 'push',},});// Add team accessawaitserver.handleRequest({method: 'github_add_repository_team',params: {owner: 'myorg',repo: 'my-project',team_slug: 'backend-team',permission: 'admin',},});

CI/CD Integration

Automate workflows and deployments:

// List workflow runsawaitserver.handleRequest({method: 'github_list_workflow_runs',params: {owner: 'myorg',repo: 'my-project',workflow_id: 'deploy.yml',},});// Re-run failed workflowawaitserver.handleRequest({method: 'github_rerun_workflow',params: {owner: 'myorg',repo: 'my-project',run_id: 123456,},});// Download build artifactsawaitserver.handleRequest({method: 'github_download_artifact',params: {owner: 'myorg',repo: 'my-project',artifact_id: 789012,},});

Webhook Management

Set up event-driven integrations:

// Create webhookawaitserver.handleRequest({method: 'github_create_webhook',params: {owner: 'myorg',repo: 'my-project',config: {url: 'https://myapp.com/webhooks',content_type: 'json',secret: 'my-secret-key',},events: ['push','pull_request','issues'],active: true,},});// List webhook deliveriesawaitserver.handleRequest({method: 'github_list_webhook_deliveries',params: {owner: 'myorg',repo: 'my-project',hook_id: 12345,},});// Redeliver failed webhookawaitserver.handleRequest({method: 'github_redeliver_webhook',params: {owner: 'myorg',repo: 'my-project',hook_id: 12345,delivery_id: 67890,},});

Release Management

Automate release workflows:

// Create releaseawaitserver.handleRequest({method: 'github_create_release',params: {owner: 'myorg',repo: 'my-project',tag_name: 'v1.0.0',name: 'Version 1.0.0',body: 'Release notes here',draft: false,prerelease: false,},});// Get latest releaseawaitserver.handleRequest({method: 'github_get_latest_release',params: {owner: 'myorg',repo: 'my-project',},});

Examples

A working example demonstrating the client's capabilities is provided in examples/basic-usage.ts:

Basic Usage Example

Demonstrates all core operations:

• Getting repository information
• Listing issues and pull requests
• Listing branches and commits
• Getting authenticated user information

Run the example:

# Using default repository (octocat/Hello-World)
GITHUB_TOKEN=your_token npm run example:basic
# Using your own repository
GITHUB_TOKEN=your_token REPO_OWNER=owner REPO_NAME=repo npm run example:basic

Note: The examples/ directory contains additional working examples including setup-new-repo.ts which demonstrates repository setup automation. See examples/README.md for details.

MCP Request/Response Format

Request Format

{method: string,// The tool/method nameparams: {// Parameters for the method[key: string]: any}}

Response Format

{success: boolean,// Whether the request succeededdata?: any,// Response data (if successful)error?: {// Error information (if failed)code: string,message: string,details?: any}}

Important Notes

GitHub Token Requirements

• A GitHub personal access token is required
• Generate one at: https://github.com/settings/tokens
• Required scopes depend on operations:
  • repo - Full repository access (for private repos)
  • public_repo - Public repository access only
  • read:user - Read user profile data
  • user:email - Read user email addresses
  • admin:repo_hook - Full control of repository hooks (webhooks)
  • admin:org - Full control of organization settings (for team operations)
  • workflow - Update GitHub Actions workflows

Rate Limiting

GitHub API has rate limits:

• Authenticated requests: 5,000 requests per hour
• Unauthenticated requests: 60 requests per hour
• Check rate limit status in response headers
• The client will throw an error if rate limited

Error Handling

All methods throw GitHubAPIError on failure:

try{constrepo=awaitclient.getRepository('owner','repo');}catch(error){if(errorinstanceofGitHubAPIError){console.error(`Error ${error.code}: ${error.message}`);console.error('Status:',error.statusCode);}}

Security Best Practices

• Never commit your GitHub token to version control
• Use environment variables for tokens
• Rotate tokens regularly
• Use minimal required scopes for your token
• Consider using GitHub Apps for production applications
• Always use webhook secrets for signature verification
• Enable Dependabot security alerts on repositories

API Documentation

For detailed GitHub API documentation, visit:

• GitHub REST API Documentation
• Octokit.js Documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.