GitHub MCP server guide

Overview

The official GitHub MCP server provides access to the GitHub API, allowing AI agents to interact with GitHub repositories, issues, pull requests, and more.

Metadata

Error: Failed to fetch metadata for MCP server "github".

Error details

# Error fetching data for github
# Failed to fetch MCP server data. See logs for details.
# Please check that the server exists in the registry and thv command is available

Usage

UI

Select the github MCP server in the ToolHive registry. In the Secrets section, add your GitHub personal access token to authenticate with the GitHub API, or select an existing secret that contains the token.

Review the optional environment variables to customize the server's behavior. For example, you might want to limit the active toolsets or enable read-only mode. Refer to the documentation for the current list of toolsets.

Security tip

Enable outbound network filtering on the Network Isolation tab to restrict the server's network access using the default profile contained in the registry.

GitHub Enterprise

If you're working with a GitHub Enterprise instance, enter the instance URL in the GITHUB_HOST environment variable and update the network isolation settings to allow access to the enterprise domain.

CLI

Run with the default configuration. ToolHive will prompt you to enter your GitHub personal access token:

thv run github

Create a secret named github containing your GitHub personal access token and run the server with the --secret flag:

thv secret set github
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github

Or, use the GitHub CLI to populate the secret with your token:

gh auth token | thv secret set github
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github

Enable network isolation using the default profile from the registry (appropriate for github.com) to restrict the server's network access:

thv run --isolate-network github

Limit the active toolsets (useful to avoid context overload) and enable read-only mode. Refer to the documentation for the current list of toolsets.

thv run -e GITHUB_TOOLSETS=repos,issues,pull_requests -e GITHUB_READ_ONLY=1 github

Enable the MCP server's dynamic tool discovery feature (currently in beta):

thv run -e GITHUB_DYNAMIC_TOOLSETS=1 github

GitHub Enterprise

Create a custom permission profile for your GitHub Enterprise instance:

github-enterprise-profile.json

{
  "network": {
    "outbound": {
      "insecure_allow_all": false,
      "allow_host": ["github.your-enterprise.com"],
      "allow_port": [443]
    }
  }
}

Then run the server with the profile:

thv run \
  -e GITHUB_HOST=https://github.your-enterprise.com \
  --isolate-network --permission-profile github-enterprise-profile.json \
  github

Kubernetes

Create a Kubernetes secret containing your GitHub personal access token:

kubectl -n toolhive-system create secret generic github-token --from-literal=token=<YOUR_TOKEN>

Create a Kubernetes manifest to deploy the GitHub MCP server using your secret:

github.yaml

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: github
  namespace: toolhive-system
spec:
  image: ghcr.io/github/github-mcp-server:v0.13.0
  transport: stdio
  port: 8080
  permissionProfile:
    type: builtin
    name: network
  secrets:
    - name: github-token
      key: token
      targetEnvName: GITHUB_PERSONAL_ACCESS_TOKEN

Apply the manifest to your Kubernetes cluster:

kubectl apply -f github.yaml

To customize the server's behavior, add environment variables to the spec section of your manifest. For example, to limit the active toolsets or enable read-only mode, add:

github.yaml

spec:
  # ...
  env:
    - name: GITHUB_TOOLSETS
      value: 'repos,issues,pull_requests'
    - name: GITHUB_READ_ONLY
      value: '1'

Refer to the documentation for the current list of toolsets.

GitHub Enterprise

If you're working with a GitHub Enterprise instance, add the GITHUB_HOST environment variable to the spec section of your manifest:

spec:
  # ...
  env:
    - name: GITHUB_HOST
      value: 'https://github.your-enterprise.com'

Sample prompts

Here are some sample prompts you can use to interact with the GitHub MCP server:

• "List all repositories for the organization my-org"
• "Create a new issue in the repository my-org/my-repo with the title 'Bug report' and the body 'There is a bug in the code'"
• "Get the latest pull requests for the repository my-org/my-repo"

Recommended practices

• Scope your GitHub personal access token to the minimum permissions required for your use case.
• Regularly rotate your GitHub personal access token and update the secret in ToolHive.
• Enable network isolation to restrict the server's outbound network access.
• Limit the active toolsets to reduce context overload and improve performance, or use dynamic tool discovery if supported by your client.