github-mcp-server-ts

GitHub MCP Server

Disclaimer!: This is not the official github MCP server, for the official one go to http://github.com/github/github-mcp-server repo. This is typescript server with my own additions of what I thought was missing on the offical server and it's base code is from the servers directory of the modelcontextprotocol repository.

---

MCP Server for the GitHub API, enabling file operations, repository management, search functionality, and more.

Features

• Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
• Comprehensive Error Handling: Clear error messages for common issues
• Git History Preservation: Operations maintain proper Git history without force pushing
• Batch Operations: Support for both single-file and multi-file operations
• Advanced Search: Support for searching code, issues/PRs, and users

Tools

1. create_or_update_file

   • Create or update a single file in a repository
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • path (string): Path where to create/update the file
     • content (string): Content of the file
     • message (string): Commit message
     • branch (string): Branch to create/update the file in
     • sha (optional string): SHA of file being replaced (for updates)
   • Returns: File content and commit details

2. push_files

   • Push multiple files in a single commit
   • Inputs:
     • owner (string): Repository owner
     • repo (string): Repository name
     • branch (string): Branch to push to
     • files (array): Files to push, each with path and content
     • message (string): Commit message
   • Returns: Updated branch reference

3. search_repositories

   • Search for GitHub repositories
   • Inputs:
     • query (string): Search query
     • page (optional number): Page number for pagination
     • perPage (optional number): Results per page (max 100)
   • Returns: Repository search results

4. create_repository

   • Create a new GitHub repository
   • Inputs:
     • name (string): Repository name
     • description (optional string): Repository description
     • private (optional boolean): Whether repo should be private
     • autoInit (optional boolean): Initialize with README
   • Returns: Created repository details

5. get_file_contents

   • Get contents of a file or directory
   • Inputs:
     • owner (string): Repository owner
     • repo (string): Repository name
     • path (string): Path to file/directory
     • branch (optional string): Branch to get contents from
   • Returns: File/directory contents

6. create_issue

   • Create a new issue
   • Inputs:
     • owner (string): Repository owner
     • repo (string): Repository name
     • title (string): Issue title
     • body (optional string): Issue description
     • assignees (optional string[]): Usernames to assign
     • labels (optional string[]): Labels to add
     • milestone (optional number): Milestone number
   • Returns: Created issue details

7. create_pull_request

   • Create a new pull request
   • Inputs:
     • owner (string): Repository owner
     • repo (string): Repository name
     • title (string): PR title
     • body (optional string): PR description
     • head (string): Branch containing changes
     • base (string): Branch to merge into
     • draft (optional boolean): Create as draft PR
     • maintainer_can_modify (optional boolean): Allow maintainer edits
   • Returns: Created pull request details

8. fork_repository

   • Fork a repository
   • Inputs:
     • owner (string): Repository owner
     • repo (string): Repository name
     • organization (optional string): Organization to fork to
   • Returns: Forked repository details

9. create_branch

   • Create a new branch
   • Inputs:
     • owner (string): Repository owner
     • repo (string): Repository name
     • branch (string): Name for new branch
     • from_branch (optional string): Source branch (defaults to repo default)
   • Returns: Created branch reference

10. list_issues

    • List and filter repository issues
    • Inputs:
      • owner (string): Repository owner
      • repo (string): Repository name
      • state (optional string): Filter by state ('open', 'closed', 'all')
      • labels (optional string[]): Filter by labels
      • sort (optional string): Sort by ('created', 'updated', 'comments')
      • direction (optional string): Sort direction ('asc', 'desc')
      • since (optional string): Filter by date (ISO 8601 timestamp)
      • page (optional number): Page number
      • per_page (optional number): Results per page
    • Returns: Array of issue details

11. update_issue

    • Update an existing issue
    • Inputs:
      • owner (string): Repository owner
      • repo (string): Repository name
      • issue_number (number): Issue number to update
      • title (optional string): New title
      • body (optional string): New description
      • state (optional string): New state ('open' or 'closed')
      • labels (optional string[]): New labels
      • assignees (optional string[]): New assignees
      • milestone (optional number): New milestone number
    • Returns: Updated issue details

12. add_issue_comment

    • Add a comment to an issue
    • Inputs:
      • owner (string): Repository owner
      • repo (string): Repository name
      • issue_number (number): Issue number to comment on
      • body (string): Comment text
    • Returns: Created comment details

13. search_code

    • Search for code across GitHub repositories
    • Inputs:
      • q (string): Search query using GitHub code search syntax
      • sort (optional string): Sort field ('indexed' only)
      • order (optional string): Sort order ('asc' or 'desc')
      • per_page (optional number): Results per page (max 100)
      • page (optional number): Page number
    • Returns: Code search results with repository context

14. search_issues

    • Search for issues and pull requests
    • Inputs:
      • q (string): Search query using GitHub issues search syntax
      • sort (optional string): Sort field (comments, reactions, created, etc.)
      • order (optional string): Sort order ('asc' or 'desc')
      • per_page (optional number): Results per page (max 100)
      • page (optional number): Page number
    • Returns: Issue and pull request search results

15. search_users

    • Search for GitHub users
    • Inputs:
      • q (string): Search query using GitHub users search syntax
      • sort (optional string): Sort field (followers, repositories, joined)
      • order (optional string): Sort order ('asc' or 'desc')
      • per_page (optional number): Results per page (max 100)
      • page (optional number): Page number
    • Returns: User search results

16. list_commits

• Gets commits of a branch in a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • page (optional string): page number
  • per_page (optional string): number of record per page
  • sha (optional string): branch name
• Returns: List of commits

17. get_issue

• Gets the contents of an issue within a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number): Issue number to retrieve
• Returns: Github Issue object & details

18. get_pull_request

• Get details of a specific pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
• Returns: Pull request details including diff and review status

19. list_pull_requests

• List and filter repository pull requests
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • state (optional string): Filter by state ('open', 'closed', 'all')
  • head (optional string): Filter by head user/org and branch
  • base (optional string): Filter by base branch
  • sort (optional string): Sort by ('created', 'updated', 'popularity', 'long-running')
  • direction (optional string): Sort direction ('asc', 'desc')
  • per_page (optional number): Results per page (max 100)
  • page (optional number): Page number
• Returns: Array of pull request details

20. create_pull_request_review

• Create a review on a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
  • body (string): Review comment text
  • event (string): Review action ('APPROVE', 'REQUEST_CHANGES', 'COMMENT')
  • commit_id (optional string): SHA of commit to review
  • comments (optional array): Line-specific comments, each with:
    • path (string): File path
    • position (number): Line position in diff
    • body (string): Comment text
• Returns: Created review details

21. merge_pull_request

• Merge a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
  • commit_title (optional string): Title for merge commit
  • commit_message (optional string): Extra detail for merge commit
  • merge_method (optional string): Merge method ('merge', 'squash', 'rebase')
• Returns: Merge result details

22. get_pull_request_files

• Get the list of files changed in a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
• Returns: Array of changed files with patch and status details

23. get_pull_request_status

• Get the combined status of all status checks for a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
• Returns: Combined status check results and individual check details

24. update_pull_request_branch

• Update a pull request branch with the latest changes from the base branch (equivalent to GitHub's "Update branch" button)
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
  • expected_head_sha (optional string): The expected SHA of the pull request's HEAD ref
• Returns: Success message when branch is updated

25. get_pull_request_comments

• Get the review comments on a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
• Returns: Array of pull request review comments with details like the comment text, author, and location in the diff

26. get_pull_request_reviews

• Get the reviews on a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
• Returns: Array of pull request reviews with details like the review state (APPROVED, CHANGES_REQUESTED, etc.), reviewer, and review body

27. list_sub_issues

• Get a list of sub-issues of a given issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number) number of the issue
  • page (optional number): Page number
  • per_page (optional number): Results per page
• Returns: Array of issue details

28. reprioritize_sub_issue

• Reorder sub_issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
  • issue_number (number) number of the issue
  • sub_issue_id (number) The id of the sub-issue to reprioritize
  • after_id (number) The id of the sub-issue to be prioritized after (either positional argument after OR before should be specified).
  • before_id (number) The id of the sub-issue to be prioritized before (either positional argument after OR before should be specified).
• Returns: sub-issue details

29. remove_sub_issue

• Remove sub_issue from issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
  • issue_number (number) number of the issue
  • sub_issue_id (number) The id of the sub-issue to be removed
• Returns: sub-issue details

30. add_sub_issue

• Get the reviews on a pull request
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • pull_number (number): Pull request number
  • issue_number (number) number of the issue
  • sub_issue_id (number) The id of the issue to be added as sub-issue
• Returns: sub-issue details

31. list_labels_for_issue

• List all labels for an issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number): Issue number
  • per_page (optional number): Results per page
  • page (optional number): Page number
• Returns: Array of label details

32. add_labels_to_issue

• Adds labels to an issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number): Issue number
  • labels (string[]): Array of label names to add
• Returns: Array of label details applied to the issue

33. set_labels_for_issue

• Sets the labels for an issue, replacing any existing labels
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number): Issue number
  • labels (optional string[]): Array of label names to set. Provide an empty array to remove all labels.
• Returns: Array of label details applied to the issue

34. remove_label_from_issue

• Remove a label from an issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number): Issue number
  • name (string): Name of the label to remove
• Returns: Success status (usually 204 No Content)

35. remove_all_labels_from_issue

• Remove all labels from an issue
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • issue_number (number): Issue number
• Returns: Success status (usually 204 No Content)

36. list_labels_for_repo

• List all labels for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • per_page (optional number): Results per page
  • page (optional number): Page number
• Returns: Array of label details for the repository

37. create_label

• Create a label for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • name (string): The name of the label
  • color (optional string): Hex color code without the leading #
  • description (optional string): A short description of the label
• Returns: Created label details

38. get_label

• Get a single label for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • name (string): The name of the label to get
• Returns: Label details

39. update_label

• Update an existing label for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • name (string): The current name of the label to update
  • new_name (optional string): The new name for the label
  • color (optional string): New hex color code
  • description (optional string): New description
• Returns: Updated label details

40. delete_label

• Delete a label from a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • name (string): The name of the label to delete
• Returns: Success status (usually 204 No Content)

41. list_labels_for_milestone

• List labels for issues in a milestone
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • milestone_number (number): Milestone number
  • per_page (optional number): Results per page
  • page (optional number): Page number
• Returns: Array of label details for the milestone

42. list_milestones

• List milestones for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • state (optional string): Filter by state ('open', 'closed', 'all', default: 'open')
  • sort (optional string): Sort by ('due_on', 'completeness', default: 'due_on')
  • direction (optional string): Sort direction ('asc', 'desc', default: 'asc')
  • per_page (optional number): Results per page
  • page (optional number): Page number
• Returns: Array of milestone details

43. create_milestone

• Create a milestone for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • title (string): Milestone title
  • state (optional string): State ('open' or 'closed', default: 'open')
  • description (optional string): Milestone description
  • due_on (optional string): Due date (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ)
• Returns: Created milestone details

44. get_milestone

• Get a single milestone for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • milestone_number (number): Milestone number
• Returns: Milestone details

45. update_milestone

• Update an existing milestone for a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • milestone_number (number): Milestone number to update
  • title (optional string): New title
  • state (optional string): New state ('open' or 'closed')
  • description (optional string): New description
  • due_on (optional string): New due date (ISO 8601 format)
• Returns: Updated milestone details

46. delete_milestone

• Delete a milestone from a repository
• Inputs:
  • owner (string): Repository owner
  • repo (string): Repository name
  • milestone_number (number): Milestone number to delete
• Returns: Success status (usually 204 No Content)

Search Query Syntax

Code Search

• language:javascript: Search by programming language
• repo:owner/name: Search in specific repository
• path:app/src: Search in specific path
• extension:js: Search by file extension
• Example: q: "import express" language:typescript path:src/

Issues Search

• is:issue or is:pr: Filter by type
• is:open or is:closed: Filter by state
• label:bug: Search by label
• author:username: Search by author
• Example: q: "memory leak" is:issue is:open label:bug

Users Search

• type:user or type:org: Filter by account type
• followers:>1000: Filter by followers
• location:London: Search by location
• Example: q: "fullstack developer" location:London followers:>100

For detailed search syntax, see GitHub's searching documentation.

Setup

Personal Access Token

Create a GitHub Personal Access Token with appropriate permissions:

• Go to Personal access tokens (in GitHub Settings > Developer settings)
• Select which repositories you'd like this token to have access to (Public, All, or Select)
• Create a token with the repo scope ("Full control of private repositories")
  • Alternatively, if working only with public repositories, select only the public_repo scope
• Copy the generated token

Usage with Claude Desktop

To use this with Claude Desktop, add the following to your claude_desktop_config.json:

Docker

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "mcp/github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Build

Docker build:

docker build -t mcp/github -f src/github/Dockerfile .

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.