github mcp server| gluon mcp

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

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

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.

[
  {
    "description": "Create or update a single file in a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "branch": {
          "description": "Branch to create/update the file in",
          "type": "string"
        },
        "content": {
          "description": "Content of the file",
          "type": "string"
        },
        "message": {
          "description": "Commit message",
          "type": "string"
        },
        "owner": {
          "description": "Repository owner (username or organization)",
          "type": "string"
        },
        "path": {
          "description": "Path where to create/update the file",
          "type": "string"
        },
        "repo": {
          "description": "Repository name",
          "type": "string"
        },
        "sha": {
          "description": "SHA of the file being replaced (required when updating existing files)",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "path",
        "content",
        "message",
        "branch"
      ],
      "type": "object"
    },
    "name": "create_or_update_file"
  },
  {
    "description": "Search for GitHub repositories",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "page": {
          "description": "Page number for pagination (default: 1)",
          "type": "number"
        },
        "perPage": {
          "description": "Number of results per page (default: 30, max: 100)",
          "type": "number"
        },
        "query": {
          "description": "Search query (see GitHub search syntax)",
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "name": "search_repositories"
  },
  {
    "description": "Create a new GitHub repository in your account",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "autoInit": {
          "description": "Initialize with README.md",
          "type": "boolean"
        },
        "description": {
          "description": "Repository description",
          "type": "string"
        },
        "name": {
          "description": "Repository name",
          "type": "string"
        },
        "private": {
          "description": "Whether the repository should be private",
          "type": "boolean"
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    },
    "name": "create_repository"
  },
  {
    "description": "Get the contents of a file or directory from a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "branch": {
          "description": "Branch to get contents from",
          "type": "string"
        },
        "owner": {
          "description": "Repository owner (username or organization)",
          "type": "string"
        },
        "path": {
          "description": "Path to the file or directory",
          "type": "string"
        },
        "repo": {
          "description": "Repository name",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "path"
      ],
      "type": "object"
    },
    "name": "get_file_contents"
  },
  {
    "description": "Push multiple files to a GitHub repository in a single commit",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "branch": {
          "description": "Branch to push to (e.g., 'main' or 'master')",
          "type": "string"
        },
        "files": {
          "description": "Array of files to push",
          "items": {
            "additionalProperties": false,
            "properties": {
              "content": {
                "type": "string"
              },
              "path": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "content"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "message": {
          "description": "Commit message",
          "type": "string"
        },
        "owner": {
          "description": "Repository owner (username or organization)",
          "type": "string"
        },
        "repo": {
          "description": "Repository name",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "branch",
        "files",
        "message"
      ],
      "type": "object"
    },
    "name": "push_files"
  },
  {
    "description": "Create a new issue in a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "assignees": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "body": {
          "type": "string"
        },
        "labels": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "milestone": {
          "type": "number"
        },
        "owner": {
          "type": "string"
        },
        "repo": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "title"
      ],
      "type": "object"
    },
    "name": "create_issue"
  },
  {
    "description": "Create a new pull request in a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "base": {
          "description": "The name of the branch you want the changes pulled into",
          "type": "string"
        },
        "body": {
          "description": "Pull request body/description",
          "type": "string"
        },
        "draft": {
          "description": "Whether to create the pull request as a draft",
          "type": "boolean"
        },
        "head": {
          "description": "The name of the branch where your changes are implemented",
          "type": "string"
        },
        "maintainer_can_modify": {
          "description": "Whether maintainers can modify the pull request",
          "type": "boolean"
        },
        "owner": {
          "description": "Repository owner (username or organization)",
          "type": "string"
        },
        "repo": {
          "description": "Repository name",
          "type": "string"
        },
        "title": {
          "description": "Pull request title",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "title",
        "head",
        "base"
      ],
      "type": "object"
    },
    "name": "create_pull_request"
  },
  {
    "description": "Fork a GitHub repository to your account or specified organization",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "organization": {
          "description": "Optional: organization to fork to (defaults to your personal account)",
          "type": "string"
        },
        "owner": {
          "description": "Repository owner (username or organization)",
          "type": "string"
        },
        "repo": {
          "description": "Repository name",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo"
      ],
      "type": "object"
    },
    "name": "fork_repository"
  },
  {
    "description": "Create a new branch in a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "branch": {
          "description": "Name for the new branch",
          "type": "string"
        },
        "from_branch": {
          "description": "Optional: source branch to create from (defaults to the repository's default branch)",
          "type": "string"
        },
        "owner": {
          "description": "Repository owner (username or organization)",
          "type": "string"
        },
        "repo": {
          "description": "Repository name",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "branch"
      ],
      "type": "object"
    },
    "name": "create_branch"
  },
  {
    "description": "Get list of commits of a branch in a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "owner": {
          "type": "string"
        },
        "page": {
          "type": "number"
        },
        "perPage": {
          "type": "number"
        },
        "repo": {
          "type": "string"
        },
        "sha": {
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo"
      ],
      "type": "object"
    },
    "name": "list_commits"
  },
  {
    "description": "List issues in a GitHub repository with filtering options",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "direction": {
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "labels": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "owner": {
          "type": "string"
        },
        "page": {
          "type": "number"
        },
        "per_page": {
          "type": "number"
        },
        "repo": {
          "type": "string"
        },
        "since": {
          "type": "string"
        },
        "sort": {
          "enum": [
            "created",
            "updated",
            "comments"
          ],
          "type": "string"
        },
        "state": {
          "enum": [
            "open",
            "closed",
            "all"
          ],
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo"
      ],
      "type": "object"
    },
    "name": "list_issues"
  },
  {
    "description": "Update an existing issue in a GitHub repository",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "assignees": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "body": {
          "type": "string"
        },
        "issue_number": {
          "type": "number"
        },
        "labels": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "milestone": {
          "type": "number"
        },
        "owner": {
          "type": "string"
        },
        "repo": {
          "type": "string"
        },
        "state": {
          "enum": [
            "open",
            "closed"
          ],
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "issue_number"
      ],
      "type": "object"
    },
    "name": "update_issue"
  },
  {
    "description": "Add a comment to an existing issue",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "body": {
          "type": "string"
        },
        "issue_number": {
          "type": "number"
        },
        "owner": {
          "type": "string"
        },
        "repo": {
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "issue_number",
        "body"
      ],
      "type": "object"
    },
    "name": "add_issue_comment"
  },
  {
    "description": "Search for code across GitHub repositories",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "order": {
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "page": {
          "minimum": 1,
          "type": "number"
        },
        "per_page": {
          "maximum": 100,
          "minimum": 1,
          "type": "number"
        },
        "q": {
          "type": "string"
        }
      },
      "required": [
        "q"
      ],
      "type": "object"
    },
    "name": "search_code"
  },
  {
    "description": "Search for issues and pull requests across GitHub repositories",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "order": {
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "page": {
          "minimum": 1,
          "type": "number"
        },
        "per_page": {
          "maximum": 100,
          "minimum": 1,
          "type": "number"
        },
        "q": {
          "type": "string"
        },
        "sort": {
          "enum": [
            "comments",
            "reactions",
            "reactions-+1",
            "reactions--1",
            "reactions-smile",
            "reactions-thinking_face",
            "reactions-heart",
            "reactions-tada",
            "interactions",
            "created",
            "updated"
          ],
          "type": "string"
        }
      },
      "required": [
        "q"
      ],
      "type": "object"
    },
    "name": "search_issues"
  },
  {
    "description": "Search for users on GitHub",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "order": {
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "page": {
          "minimum": 1,
          "type": "number"
        },
        "per_page": {
          "maximum": 100,
          "minimum": 1,
          "type": "number"
        },
        "q": {
          "type": "string"
        },
        "sort": {
          "enum": [
            "followers",
            "repositories",
            "joined"
          ],
          "type": "string"
        }
      },
      "required": [
        "q"
      ],
      "type": "object"
    },
    "name": "search_users"
  },
  {
    "description": "Get details of a specific issue in a GitHub repository.",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "issue_number": {
          "type": "number"
        },
        "owner": {
          "type": "string"
        },
        "repo": {
          "type": "string"
        }
      },
      "required": [
        "owner",
        "repo",
        "issue_number"
      ],
      "type": "object"
    },
    "name": "get_issue"
  }
]