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';

const server = new MCPServer(process.env.GITHUB_TOKEN);

// Get authenticated user
const response = await server.handleRequest({
  method: 'github_get_authenticated_user',
  params: {},
});

if (response.success) {
  console.log('User:', response.data);
}

// Search repositories
const searchResponse = await server.handleRequest({
  method: 'github_search_repositories',
  params: {
    q: 'typescript',
    per_page: 10,
  },
});

Using the GitHub Client Directly

import { GitHubClient } from '@onamfc/mcp-github-integration';

const client = new GitHubClient({
  token: process.env.GITHUB_TOKEN,
});

// Create a new repository
const newRepo = await client.createRepository({
  name: 'my-awesome-project',
  description: 'My awesome project description',
  private: false,
  auto_init: true,
});

// Get repository information
const repo = await client.getRepository('owner', 'repo-name');
console.log(repo);

// Create an issue
const issue = await client.createIssue({
  owner: 'owner',
  repo: 'repo-name',
  title: 'Bug Report',
  body: 'Description of the bug',
  labels: ['bug'],
});

// List pull requests
const prs = await client.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 configuration
await server.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 settings
await server.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 discoverability
await server.handleRequest({
  method: 'github_replace_repository_topics',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    topics: ['javascript', 'api', 'automation'],
  },
});

Team & Access Management

Manage collaborators and permissions:

// Add collaborator
await server.handleRequest({
  method: 'github_add_collaborator',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    username: 'developer123',
    permission: 'push',
  },
});

// Add team access
await server.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 runs
await server.handleRequest({
  method: 'github_list_workflow_runs',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    workflow_id: 'deploy.yml',
  },
});

// Re-run failed workflow
await server.handleRequest({
  method: 'github_rerun_workflow',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    run_id: 123456,
  },
});

// Download build artifacts
await server.handleRequest({
  method: 'github_download_artifact',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    artifact_id: 789012,
  },
});

Webhook Management

Set up event-driven integrations:

// Create webhook
await server.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 deliveries
await server.handleRequest({
  method: 'github_list_webhook_deliveries',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    hook_id: 12345,
  },
});

// Redeliver failed webhook
await server.handleRequest({
  method: 'github_redeliver_webhook',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    hook_id: 12345,
    delivery_id: 67890,
  },
});

Release Management

Automate release workflows:

// Create release
await server.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 release
await server.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 name
  params: {              // Parameters for the method
    [key: string]: any
  }
}

Response Format

{
  success: boolean,      // Whether the request succeeded
  data?: 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 {
  const repo = await client.getRepository('owner', 'repo');
} catch (error) {
  if (error instanceof GitHubAPIError) {
    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.