GitHub MCP Server

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
• Project Management: Complete toolset for GitHub Projects (classic) management, including creating projects, managing columns, and working with cards

Tools

1. create_or_update_file
2. Create or update a single file in a repository
3. 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)

4. Returns: File content and commit details

5. push_files

6. Push multiple files in a single commit
7. 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

8. Returns: Updated branch reference

9. search_repositories

10. Search for GitHub repositories
11. Inputs:
    • query (string): Search query
    • page (optional number): Page number for pagination
    • perPage (optional number): Results per page (max 100)

12. Returns: Repository search results

13. create_repository

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

16. Returns: Created repository details

17. get_file_contents

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

20. Returns: File/directory contents

21. create_issue

22. Create a new issue
23. 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

24. Returns: Created issue details

25. create_pull_request

26. Create a new pull request
27. 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

28. Returns: Created pull request details

29. fork_repository

30. Fork a repository
31. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • organization (optional string): Organization to fork to

32. Returns: Forked repository details

33. create_branch

34. Create a new branch
35. 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)

36. Returns: Created branch reference

37. 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

38. 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

39. 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

40. 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

41. 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

42. 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

43. list_commits

44. Gets commits of a branch in a repository
45. 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

46. Returns: List of commits

47. get_issue

48. Gets the contents of an issue within a repository
49. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • issue_number (number): Issue number to retrieve

50. Returns: Github Issue object & details

51. delete_issue

52. Deletes an issue from a GitHub repository using GraphQL API
53. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • issue_number (number): Issue number to delete

54. Returns: Deletion confirmation with repository information

55. get_pull_request

56. Get details of a specific pull request
57. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • pull_number (number): Pull request number

58. Returns: Pull request details including diff and review status

59. list_pull_requests

60. List and filter repository pull requests
61. 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

62. Returns: Array of pull request details

63. create_pull_request_review

64. Create a review on a pull request
65. 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

66. Returns: Created review details

67. merge_pull_request

68. Merge a pull request
69. 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')

70. Returns: Merge result details

71. get_pull_request_files

72. Get the list of files changed in a pull request
73. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • pull_number (number): Pull request number

74. Returns: Array of changed files with patch and status details

75. get_pull_request_status

76. Get the combined status of all status checks for a pull request
77. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • pull_number (number): Pull request number

78. Returns: Combined status check results and individual check details

79. update_pull_request_branch

80. Update a pull request branch with the latest changes from the base branch (equivalent to GitHub's "Update branch" button)
81. 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

82. Returns: Success message when branch is updated

83. get_pull_request_comments

84. Get the review comments on a pull request
85. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • pull_number (number): Pull request number

86. Returns: Array of pull request review comments with details like the comment text, author, and location in the diff

87. get_pull_request_reviews

88. Get the reviews on a pull request
89. Inputs:
    • owner (string): Repository owner
    • repo (string): Repository name
    • pull_number (number): Pull request number

90. Returns: Array of pull request reviews with details like the review state (APPROVED, CHANGES_REQUESTED, etc.), reviewer, and review body

91. create_project

92. Create a new project in a GitHub repository
93. Inputs:
    • owner (string): Repository owner (username or organization)
    • repo (string): Repository name
    • name (string): Name of the project
    • body (optional string): Description of the project

94. Returns: Created project details

95. get_project

96. Get details about a specific project
97. Inputs:
    • owner (string): Repository owner (username or organization)
    • repo (string): Repository name
    • project_number (number): The project number

98. Returns: Project details

99. update_project

100. Update an existing project's details
101. Inputs:
     • project_id (number): The unique identifier of the project
     • name (optional string): New name of the project
     • body (optional string): New description of the project
     • state (optional string): State of the project ('open' or 'closed')

102. Returns: Updated project details

103. list_projects

104. List all projects in a GitHub repository
105. Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • state (optional string): Filter projects by state ('open', 'closed', 'all')
     • page (optional number): Page number for pagination (starts at 1)
     • per_page (optional number): Number of results per page (max 100)

106. Returns: Array of project details

107. create_project_column

108. Create a new column in a project
109. Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • project_number (number): The project number
     • name (string): Name of the column

110. Returns: Created column details

111. list_project_columns

112. List all columns in a project
113. Inputs:
     • project_id (number): The unique identifier of the project
     • page (optional number): Page number for pagination (starts at 1)
     • per_page (optional number): Number of results per page (max 100)

114. Returns: Array of project column details

115. update_project_column

116. Update an existing project column
117. Inputs:
     • column_id (number): The unique identifier of the column
     • name (string): New name of the column

118. Returns: Updated column details

119. delete_project_column

120. Delete a project column
121. Inputs:
     • column_id (number): The unique identifier of the column

122. Returns: Success message

123. add_card_to_column

124. Add a new card to a project column
125. Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • column_id (string): The ID of the column to add card to
     • content_type (string): Type of content for the card ('Issue', 'PullRequest', 'Note')
     • content_id (optional number): ID of the issue or pull request (required if content_type is Issue or PullRequest)
     • note (optional string): The note content for the card (required if content_type is Note)

126. Returns: Created card details

127. list_column_cards

128. List all cards in a project column
129. Inputs:
     • column_id (number): The unique identifier of the column
     • archived_state (optional string): Filter by card archived state ('all', 'archived', 'not_archived')
     • page (optional number): Page number for pagination (starts at 1)
     • per_page (optional number): Number of results per page (max 100)

130. Returns: Array of card details

131. move_card

132. Move a card to a different position or column
133. Inputs:
     • card_id (number): The unique identifier of the card
     • position (string): The position of the card ('top', 'bottom', or 'after:')
     • column_id (optional number): The column ID to move the card to

134. Returns: Success message

135. delete_card

136. Delete a card from a project
137. Inputs:
     • card_id (number): The unique identifier of the card

138. Returns: Success message

139. list_organization_projects

140. List all projects in a GitHub organization (at organization level, not repository level)
141. Inputs:
     • org (string): Organization name
     • state (optional string): Filter projects by state ('open', 'closed', 'all')
     • page (optional number): Page number for pagination
     • per_page (optional number): Number of results per page (max 100)
142. Returns: Array of organization project details

Projects V2 Tools (GitHub's New Projects Experience)

1. list_organization_projects_v2
2. List projects V2 in a GitHub organization using GraphQL API
3. Inputs:
   • org (string): Organization name
   • first (optional number): Number of projects to fetch (max 100)
   • after (optional string): Cursor for pagination
   • orderBy (optional object): How to order the projects

4. Returns: Array of projects with pagination info

5. get_project_v2

6. Get details of a GitHub project V2 using GraphQL API
7. Inputs:
   • id (string): The node ID of the project

8. Returns: Detailed project information including fields and views

9. create_project_v2

10. Create a new GitHub project V2 using GraphQL API
11. Inputs:
    • ownerId (string): The node ID of the organization or user
    • title (string): Title of the project
    • description (optional string): Description of the project

12. Returns: Created project details

13. update_project_v2

14. Update a GitHub project V2 using GraphQL API
15. Inputs:
    • projectId (string): The node ID of the project
    • title (optional string): New title for the project
    • description (optional string): New description for the project
    • closed (optional boolean): Whether to close the project

16. Returns: Updated project details

17. add_item_to_project_v2

18. Add an issue or pull request to a GitHub project V2 using GraphQL API
19. Inputs:
    • projectId (string): The node ID of the project
    • contentId (string): The node ID of the issue or pull request to add

20. Returns: Added item details

21. list_project_v2_items

22. List items in a GitHub project V2 using GraphQL API
23. Inputs:
    • projectId (string): The node ID of the project
    • first (optional number): Number of items to fetch (max 100)
    • after (optional string): Cursor for pagination
    • filterBy (optional object): Filters for the items

24. Returns: Array of project items with their field values

25. update_project_v2_item_field

26. Update a field value for an item in a GitHub project V2 using GraphQL API
27. Inputs:
    • projectId (string): The node ID of the project
    • itemId (string): The node ID of the item
    • fieldId (string): The node ID of the field
    • value (any): The new value for the field
28. Returns: Updated item details

Project Management Notes

Deprecation Warning: GitHub has announced that Projects (classic) is being deprecated in favor of the new Projects experience. Tools 27-39 work with the classic version of Projects, which may be removed in the future. For the new GitHub Projects experience, use tools 40-46 instead.

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 - For using the Projects V2 tools, make sure to include the project scope as well - 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",
        "ghcr.io/tuanle96/mcp-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@earnbasejs/mcp-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.