|
| 1 | +--- |
| 2 | +title: Using the GitHub MCP Server |
| 3 | +intro: "Learn how to use the GitHub Model Context Protocol (MCP) server to extend {% data variables.copilot.copilot_chat_short %}." |
| 4 | +shortTitle: Use the GitHub MCP Server |
| 5 | +versions: |
| 6 | + feature: copilot |
| 7 | +topics: |
| 8 | + - Copilot |
| 9 | +type: how_to |
| 10 | +--- |
| 11 | + |
| 12 | +>[!NOTE] |
| 13 | +> The {% data variables.product.github %} MCP server is currently in {% data variables.release-phases.public_preview %} and subject to change. |
| 14 | +
|
| 15 | +{% data reusables.copilot.mcp.about-github-mcp-server %} |
| 16 | + |
| 17 | +## Setting up the {% data variables.product.github %} MCP server in {% data variables.product.prodname_vscode %} |
| 18 | + |
| 19 | +The instructions below guide you through setting up the {% data variables.product.github %} MCP server in {% data variables.product.prodname_vscode %}. Other MCP-compatible editors may have similar steps, but the exact process may vary. |
| 20 | + |
| 21 | +You can choose to set up the {% data variables.product.github %} MCP server either remotely or locally, depending on your needs and preferences. You can also configure your {% data variables.product.github %} MCP server for either: |
| 22 | + |
| 23 | +{% data reusables.copilot.mcp.mcp-configuration-location %} |
| 24 | + |
| 25 | +The remote {% data variables.product.github %} MCP server uses one-click OAuth authentication by default, but you can also manually configure it to use a {% data variables.product.pat_generic %} (PAT) for authentication. If you use OAuth, the MCP server will have the same access as your personal account. If you use a PAT, the MCP server will have access to the scopes granted by the PAT. |
| 26 | + |
| 27 | +> [!NOTE] |
| 28 | +> If you are an {% data variables.product.prodname_emu %} with PAT restrictions, you won't be able to use PAT authentication. If you have OAuth access policy restrictions, you will need the OAuth apps for each client to be enabled (except {% data variables.product.prodname_vscode %} and {% data variables.product.prodname_vs %}). |
| 29 | +
|
| 30 | +* [Remote MCP server configuration with OAuth](#remote-mcp-server-configuration-with-oauth) |
| 31 | +* [Remote MCP server configuration with PAT](#remote-mcp-server-configuration-with-pat) |
| 32 | +* [Local MCP server setup](#local-mcp-server-setup) |
| 33 | + |
| 34 | +### Remote MCP server configuration with OAuth |
| 35 | + |
| 36 | +> [!NOTE] |
| 37 | +> The remote {% data variables.product.github %} MCP server is not available to {% data variables.product.prodname_ghe_server %} users. If you are using {% data variables.product.prodname_ghe_server %}, you can install the {% data variables.product.github %} MCP server locally. See [Local MCP server setup](#local-mcp-server-setup). |
| 38 | +
|
| 39 | +You do not need to create a PAT or install any additional software to use the remote {% data variables.product.github %} MCP server with OAuth. You can set it up directly in {% data variables.product.prodname_vscode %}. You can also install individual toolsets, either in read-only mode or with full read/write access, allowing you to tailor the server's capabilities to your specific needs. For more information, see [Tool configuration](#tool-configuration). |
| 40 | + |
| 41 | +1. In {% data variables.product.prodname_vscode %}, open the command palette by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) / <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Mac). |
| 42 | +1. Type: `mcp: add server` and then press **Enter**. |
| 43 | +1. From the list, select **HTTP (HTTP or Server-Sent Events)**. |
| 44 | +1. In the **Server URL** field, enter `https://api.githubcopilot.com/mcp/`, and press **Enter**. |
| 45 | +1. Under **Enter Server ID**, press **Enter** to use the default server ID, or enter a custom server ID. |
| 46 | +1. Under **Choose where to save the configuration**, select where you want to save the MCP server configuration. |
| 47 | + |
| 48 | + * {% data variables.product.prodname_vscode %} will open and add the configuration to the selected file in the editor, or create a new file if it doesn't exist. |
| 49 | + |
| 50 | +1. In the **{% data variables.product.prodname_vscode %}** popup, to authorize the MCP server with OAuth, click **Allow** and select your personal account from the list. |
| 51 | + |
| 52 | +### Remote MCP server configuration with PAT |
| 53 | + |
| 54 | +To configure the remote {% data variables.product.github %} MCP server with a PAT, ensure you have created a PAT with the necessary scopes for the access you want to grant to the MCP server. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). |
| 55 | + |
| 56 | +You will need to manually configure the MCP server in {% data variables.product.prodname_vscode %} to use the PAT for authorization. |
| 57 | + |
| 58 | +1. In {% data variables.product.prodname_vscode %}, open the command palette by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) / <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Mac). |
| 59 | +1. Type: `mcp: add server` and then press **Enter**. |
| 60 | +1. From the list, select **HTTP (HTTP or Server-Sent Events)**. |
| 61 | +1. In the **Server URL** field, enter `https://api.githubcopilot.com/mcp/`, and press **Enter**. |
| 62 | +1. Under **Enter Server ID**, press **Enter** to use the default server ID, or enter a custom server ID. |
| 63 | +1. Under **Choose where to save the configuration**, select where you want to save the MCP server configuration. |
| 64 | + |
| 65 | + * {% data variables.product.prodname_vscode %} will open and add the configuration to the selected file in the editor, or create a new file if it doesn't exist. |
| 66 | + |
| 67 | +1. In the **{% data variables.product.prodname_vscode %}** popup, to decline OAuth authorization, click **Cancel**. |
| 68 | +1. You will need to manually edit the configuration file to use a PAT. In the configuration file, at the end of the `url` line, add the following: |
| 69 | + |
| 70 | + ```json copy |
| 71 | + , |
| 72 | + "headers": { |
| 73 | + "Authorization": "Bearer ${input:github_token}" |
| 74 | + } |
| 75 | + }, |
| 76 | + }, |
| 77 | + "inputs": [ |
| 78 | + { |
| 79 | + "id": "github_token", |
| 80 | + "type": "promptString", |
| 81 | + "description": "{% data variables.product.github %} {% data variables.product.pat_generic_title_case %}", |
| 82 | + "password": true |
| 83 | + } |
| 84 | + ] |
| 85 | + } |
| 86 | + ``` |
| 87 | + |
| 88 | +1. A "Restart" button will appear in the file. Click "Restart" to restart the MCP server with the new configuration. |
| 89 | + |
| 90 | +  |
| 91 | + |
| 92 | +1. In the command palette, you will see a prompt to enter your GitHub token. Enter the PAT you created earlier, and press **Enter**. |
| 93 | + * The MCP server will now be configured to use the PAT for authorization. |
| 94 | + |
| 95 | +### Local MCP server setup |
| 96 | + |
| 97 | +>[!NOTE] |
| 98 | +> If you are a {% data variables.product.prodname_ghe_server %} user, and your enterprise has PAT restrictions enabled, you can only use API endpoints for scopes that are allowed by your enterprise's PAT policy. If all API endpoints are restricted, you will not be able to use the MCP server. If you are unsure about your enterprise's PAT policy, contact your enterprise administrator for more information. |
| 99 | + |
| 100 | +Using the {% data variables.product.github %} MCP server locally requires you to have Docker installed and running on your machine. Additionally, you can only authenticate with a PAT, as OAuth is not supported for local MCP servers. |
| 101 | + |
| 102 | +1. Ensure you have Docker installed and running on your machine. See [Docker installation instructions](https://docs.docker.com/get-docker/). |
| 103 | +1. Create a PAT with (at least) the `read:packages` and `repo` scopes. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). |
| 104 | +1. Decide whether you want to configure the MCP server for a specific repository or for your personal instance of {% data variables.product.prodname_vscode %}. |
| 105 | + |
| 106 | + * If you are using a specific repository, open the `.vscode/mcp.json` file in {% data variables.product.prodname_vscode %}, and add the following configuration: |
| 107 | + |
| 108 | + ```json copy |
| 109 | + { |
| 110 | + "inputs": [ |
| 111 | + { |
| 112 | + "type": "promptString", |
| 113 | + "id": "github_token", |
| 114 | + "description": "{% data variables.product.github %} {% data variables.product.pat_generic_title_case %}", |
| 115 | + "password": true |
| 116 | + } |
| 117 | + ], |
| 118 | + "servers": { |
| 119 | + "github": { |
| 120 | + "command": "docker", |
| 121 | + "args": [ |
| 122 | + "run", |
| 123 | + "-i", |
| 124 | + "--rm", |
| 125 | + "-e", |
| 126 | + "GITHUB_PERSONAL_ACCESS_TOKEN", |
| 127 | + "ghcr.io/github/github-mcp-server" |
| 128 | + ], |
| 129 | + "env": { |
| 130 | + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" |
| 131 | + } |
| 132 | + } |
| 133 | + } |
| 134 | + } |
| 135 | + ``` |
| 136 | + |
| 137 | + * If you are using your personal instance of {% data variables.product.prodname_vscode %}, open your `settings.json` file in {% data variables.product.prodname_vscode %}: |
| 138 | + * Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (macOS). |
| 139 | + * Type **Preferences: Open Settings (JSON)** and select it. |
| 140 | + * Add the following configuration: |
| 141 | + |
| 142 | + ```json copy |
| 143 | + { |
| 144 | + "mcp": { |
| 145 | + "inputs": [ |
| 146 | + { |
| 147 | + "type": "promptString", |
| 148 | + "id": "github_token", |
| 149 | + "description": "{% data variables.product.github %} {% data variables.product.pat_generic_title_case %}", |
| 150 | + "password": true |
| 151 | + } |
| 152 | + ], |
| 153 | + "servers": { |
| 154 | + "github": { |
| 155 | + "command": "docker", |
| 156 | + "args": [ |
| 157 | + "run", |
| 158 | + "-i", |
| 159 | + "--rm", |
| 160 | + "-e", |
| 161 | + "GITHUB_PERSONAL_ACCESS_TOKEN", |
| 162 | + "ghcr.io/github/github-mcp-server" |
| 163 | + ], |
| 164 | + "env": { |
| 165 | + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" |
| 166 | + } |
| 167 | + } |
| 168 | + } |
| 169 | + } |
| 170 | + } |
| 171 | + ``` |
| 172 | + |
| 173 | +1. Save the file. |
| 174 | +1. In the command palette, you will see a prompt to enter your {% data variables.product.github %} token. Enter the PAT you created earlier, and press **Enter**. |
| 175 | + * The MCP server will now be configured to run locally with the PAT for authorization. |
| 176 | + |
| 177 | +## Tool configuration |
| 178 | + |
| 179 | +The {% data variables.product.github %} MCP server supports installing individual toolsets, either in read-only mode or with full read/write access, allowing you to tailor the server's capabilities to your specific needs. For one-click installation options of each toolset, see the [GitHub MCP server repository](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md). |
| 180 | + |
| 181 | +## Using the {% data variables.product.github %} MCP server in {% data variables.product.prodname_vscode %} |
| 182 | + |
| 183 | +The {% data variables.product.github %} MCP server enables you to perform a wide range of actions on {% data variables.product.github %}, via {% data variables.copilot.copilot_chat_short %} in {% data variables.product.prodname_vscode %}. |
| 184 | + |
| 185 | +{% data reusables.copilot.open-chat-vs-code %} |
| 186 | +{% data reusables.copilot.select-agent %} |
| 187 | +1. To see the available actions, in the {% data variables.copilot.copilot_chat_short %} box, click the **Select tools** icon. |
| 188 | + * In the **Tools** dropdown, under **MCP Server:{% data variables.product.github %}**, you will see a list of available actions. |
| 189 | +1. In the {% data variables.copilot.copilot_chat_short %} box, type a command or question related to the action you want to perform, and press **Enter**. |
| 190 | + * For example, you can ask the {% data variables.product.github %} MCP server to create a new issue, list pull requests, or retrieve repository information. |
| 191 | +1. The {% data variables.product.github %} MCP server will process your request and provide a response in the chat interface. |
| 192 | + * In the {% data variables.copilot.copilot_chat_short %} box, you may be asked to give additional permissions or provide more information to complete the action. |
| 193 | +1. Follow the prompts to complete the action. |
| 194 | + |
| 195 | +{% data reusables.copilot.mcp.troubleshooting-mcp-server %} |
| 196 | + |
| 197 | +## Further reading |
| 198 | + |
| 199 | +* [AUTOTITLE](/copilot/customizing-copilot/using-model-context-protocol/extending-copilot-coding-agent-with-mcp) |
0 commit comments