chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,112 @@
|
||||
# GitHub MCP Server Installation Guides
|
||||
|
||||
This directory contains detailed installation instructions for the GitHub MCP Server across different host applications and IDEs. Choose the guide that matches your development environment.
|
||||
|
||||
## Installation Guides by Host Application
|
||||
- **[Copilot CLI](install-copilot-cli.md)** - Installation guide for GitHub Copilot CLI
|
||||
- **[GitHub Copilot in other IDEs](install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
|
||||
- **[Antigravity](install-antigravity.md)** - Installation for Google Antigravity IDE
|
||||
- **[Claude Applications](install-claude.md)** - Installation guide for Claude Desktop and Claude Code CLI
|
||||
- **[Cline](install-cline.md)** - Installation guide for Cline
|
||||
- **[Cursor](install-cursor.md)** - Installation guide for Cursor IDE
|
||||
- **[Google Gemini CLI](install-gemini-cli.md)** - Installation guide for Google Gemini CLI
|
||||
- **[OpenAI Codex](install-codex.md)** - Installation guide for OpenAI Codex
|
||||
- **[OpenCode](install-opencode.md)** - Installation guide for the OpenCode terminal agent
|
||||
- **[Roo Code](install-roo-code.md)** - Installation guide for Roo Code
|
||||
- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE
|
||||
- **[Xcode (Codex & Claude Agent)](install-xcode.md)** - Installation guide for Codex and Claude Agent within Xcode
|
||||
- **[Zed](install-zed.md)** - Installation guide for Zed editor
|
||||
|
||||
## Support by Host Application
|
||||
|
||||
| Host Application | Local GitHub MCP Support | Remote GitHub MCP Support | Prerequisites | Difficulty |
|
||||
|-----------------|---------------|----------------|---------------|------------|
|
||||
| Copilot CLI | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Copilot in VS Code | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: VS Code 1.101+ | Easy |
|
||||
| Copilot Coding Agent | ✅ | ✅ Full (on by default; no auth needed) | Any _paid_ copilot license | Default on |
|
||||
| Copilot in Visual Studio | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: Visual Studio 17.14+ | Easy |
|
||||
| Copilot in JetBrains | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: JetBrains Copilot Extension v1.5.53+ | Easy |
|
||||
| Claude Code | ✅ | ✅ PAT + ❌ No OAuth| GitHub MCP Server binary or remote URL, GitHub PAT | Easy |
|
||||
| Claude Desktop | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Moderate |
|
||||
| Cline | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Cursor | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Google Gemini CLI | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| OpenCode | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Roo Code | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Windsurf | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Zed | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
|
||||
| Copilot in Xcode | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: Copilot for Xcode 0.41.0+ | Easy |
|
||||
| Copilot in Eclipse | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: Eclipse Plug-in for Copilot 0.10.0+ | Easy |
|
||||
| Xcode (Codex) | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker (full path required), GitHub PAT<br>Remote: GitHub PAT via `GITHUB_PAT_TOKEN` env var (`bearer_token_env_var`) | Easy |
|
||||
| Xcode (Claude Agent) | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker (full path required), GitHub PAT<br>Remote: GitHub PAT | Easy |
|
||||
|
||||
**Legend:**
|
||||
- ✅ = Fully supported
|
||||
- ❌ = Not yet supported
|
||||
|
||||
**Note:** Remote MCP support requires host applications to register a GitHub App or OAuth app for OAuth flow support – even if the new OAuth spec is supported by that host app. Currently, only VS Code has full remote GitHub server support.
|
||||
|
||||
## Installation Methods
|
||||
|
||||
The GitHub MCP Server can be installed using several methods. **Docker is the most popular and recommended approach** for most users, but alternatives are available depending on your needs:
|
||||
|
||||
### 🐳 Docker (Most Common & Recommended)
|
||||
- **Pros**: No local build required, consistent environment, easy updates, works across all platforms
|
||||
- **Cons**: Requires Docker installed and running
|
||||
- **Best for**: Most users, especially those already using Docker or wanting the simplest setup
|
||||
- **Used by**: Claude Desktop, Copilot in VS Code, Cursor, Windsurf, etc.
|
||||
|
||||
### 📦 Pre-built Binary (Lightweight Alternative)
|
||||
- **Pros**: No Docker required, direct execution via stdio, minimal setup
|
||||
- **Cons**: Need to manually download and manage updates, platform-specific binaries
|
||||
- **Best for**: Minimal environments, users who prefer not to use Docker
|
||||
- **Used by**: Claude Code CLI, lightweight setups
|
||||
|
||||
### 🔨 Build from Source (Advanced Users)
|
||||
- **Pros**: Latest features, full customization, no external dependencies
|
||||
- **Cons**: Requires Go development environment, more complex setup
|
||||
- **Prerequisites**: [Go 1.24+](https://go.dev/doc/install)
|
||||
- **Build command**: `go build -o github-mcp-server cmd/github-mcp-server/main.go`
|
||||
- **Best for**: Developers who want the latest features or need custom modifications
|
||||
|
||||
### Important Notes on the GitHub MCP Server
|
||||
|
||||
- **Docker Image**: The official Docker image is now `ghcr.io/github/github-mcp-server`
|
||||
- **npm Package**: The npm package @modelcontextprotocol/server-github is no longer supported as of April 2025
|
||||
- **Remote Server**: The remote server URL is `https://api.githubcopilot.com/mcp/`
|
||||
|
||||
## General Prerequisites
|
||||
|
||||
All installations with Personal Access Tokens (PAT) require:
|
||||
- **GitHub Personal Access Token (PAT)**: [Create one here](https://github.com/settings/personal-access-tokens/new)
|
||||
|
||||
Optional (depending on installation method):
|
||||
- **Docker** (for Docker-based installations): [Download Docker](https://www.docker.com/)
|
||||
- **Go 1.24+** (for building from source): [Install Go](https://go.dev/doc/install)
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
Regardless of which installation method you choose, follow these security guidelines:
|
||||
|
||||
1. **Secure Token Storage**: Never commit your GitHub PAT to version control
|
||||
2. **Limit Token Scope**: Only grant necessary permissions to your GitHub PAT
|
||||
3. **File Permissions**: Restrict access to configuration files containing tokens
|
||||
4. **Regular Rotation**: Periodically rotate your GitHub Personal Access Tokens
|
||||
5. **Environment Variables**: Use environment variables when supported by your host
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
1. Check the troubleshooting section in your specific installation guide
|
||||
2. Verify your GitHub PAT has the required permissions
|
||||
3. Ensure Docker is running (for local installations)
|
||||
4. Review your host application's logs for error messages
|
||||
5. Consult the main [README.md](README.md) for additional configuration options
|
||||
|
||||
## Configuration Options
|
||||
|
||||
After installation, you may want to explore:
|
||||
- **Toolsets**: Enable/disable specific GitHub API capabilities
|
||||
- **Read-Only Mode**: Restrict to read-only operations
|
||||
- **Lockdown Mode**: Hide public issue details created by users without push access
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# Installing GitHub MCP Server in Antigravity
|
||||
|
||||
This guide covers setting up the GitHub MCP Server in Google's Antigravity IDE.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Antigravity IDE installed (latest version)
|
||||
- GitHub Personal Access Token with appropriate scopes
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Option 1: Remote Server (Recommended)
|
||||
|
||||
Uses GitHub's hosted server at `https://api.githubcopilot.com/mcp/`.
|
||||
|
||||
> [!NOTE]
|
||||
> We recommend this manual configuration method because the "official" installation via the Antigravity MCP Store currently has known issues (often resulting in Docker errors). This direct remote connection is more reliable.
|
||||
|
||||
#### Step 1: Access MCP Configuration
|
||||
|
||||
1. Open Antigravity
|
||||
2. Click the "..." (Additional Options) menu in the Agent panel
|
||||
3. Select "MCP Servers"
|
||||
4. Click "Manage MCP Servers"
|
||||
5. Click "View raw config"
|
||||
|
||||
This will open your `mcp_config.json` file at:
|
||||
- **Windows**: `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json`
|
||||
- **macOS/Linux**: `~/.gemini/antigravity/mcp_config.json`
|
||||
|
||||
#### Step 2: Add Configuration
|
||||
|
||||
Add the following to your `mcp_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"serverUrl": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important**: Note that Antigravity uses `serverUrl` instead of `url` for HTTP-based MCP servers.
|
||||
|
||||
#### Step 3: Configure Your Token
|
||||
|
||||
Replace `YOUR_GITHUB_PAT` with your actual GitHub Personal Access Token.
|
||||
|
||||
Create a token here: https://github.com/settings/tokens
|
||||
|
||||
Recommended scopes:
|
||||
- `repo` - Full control of private repositories
|
||||
- `read:org` - Read org and team membership
|
||||
- `read:user` - Read user profile data
|
||||
|
||||
#### Step 4: Restart Antigravity
|
||||
|
||||
Close and reopen Antigravity for the changes to take effect.
|
||||
|
||||
#### Step 5: Verify Installation
|
||||
|
||||
1. Open the MCP Servers panel (... menu → MCP Servers)
|
||||
2. You should see "github" with a list of available tools
|
||||
3. You can now use GitHub tools in your conversations
|
||||
|
||||
> [!NOTE]
|
||||
> The status indicator in the MCP Servers panel might not immediately turn green in some versions, but the tools will still function if configured correctly.
|
||||
|
||||
### Option 2: Local Docker Server
|
||||
|
||||
If you prefer running the server locally with Docker:
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Requirements**:
|
||||
- Docker Desktop installed and running
|
||||
- Docker must be in your system PATH
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Error: serverUrl or command must be specified"
|
||||
|
||||
Make sure you're using `serverUrl` (not `url`) for the remote server configuration. Antigravity requires `serverUrl` for HTTP-based MCP servers.
|
||||
|
||||
### Server not appearing in MCP list
|
||||
|
||||
- Verify JSON syntax in your config file
|
||||
- Check that your PAT hasn't expired
|
||||
- Restart Antigravity completely
|
||||
|
||||
### Tools not working
|
||||
|
||||
- Ensure your PAT has the correct scopes
|
||||
- Check the MCP Servers panel for error messages
|
||||
- Verify internet connection for remote server
|
||||
|
||||
## Available Tools
|
||||
|
||||
Once installed, you'll have access to tools like:
|
||||
- `create_repository` - Create new GitHub repositories
|
||||
- `push_files` - Push files to repositories
|
||||
- `search_repositories` - Search for repositories
|
||||
- `create_or_update_file` - Manage file content
|
||||
- `get_file_contents` - Read file content
|
||||
- And many more...
|
||||
|
||||
For a complete list of available tools and features, see the [main README](../../README.md).
|
||||
|
||||
## Differences from Other IDEs
|
||||
|
||||
- **Configuration key**: Antigravity uses `serverUrl` instead of `url` for HTTP servers
|
||||
- **Config location**: `.gemini/antigravity/mcp_config.json` instead of `.cursor/mcp.json`
|
||||
- **Tool limits**: Antigravity recommends keeping total enabled tools under 50 for optimal performance
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Explore the [Server Configuration Guide](../server-configuration.md) for advanced options
|
||||
- Check out [toolsets documentation](../../README.md#available-toolsets) to customize available tools
|
||||
- See the [Remote Server Documentation](../remote-server.md) for more details
|
||||
@@ -0,0 +1,342 @@
|
||||
# Install GitHub MCP Server in Claude Applications
|
||||
|
||||
## Claude Code CLI
|
||||
|
||||
### Prerequisites
|
||||
- Claude Code CLI installed
|
||||
- [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
|
||||
- For local setup: [Docker](https://www.docker.com/) installed and running
|
||||
- Open Claude Code inside the directory for your project (recommended for best experience and clear scope of configuration)
|
||||
|
||||
<details>
|
||||
<summary><b>Storing Your PAT Securely</b></summary>
|
||||
<br>
|
||||
|
||||
For security, avoid hardcoding your token. One common approach:
|
||||
|
||||
1. Store your token in `.env` file
|
||||
```
|
||||
GITHUB_PAT=your_token_here
|
||||
```
|
||||
|
||||
2. Add to .gitignore
|
||||
```bash
|
||||
echo -e ".env\n.mcp.json" >> .gitignore
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Remote Server Setup (Streamable HTTP)
|
||||
|
||||
> **Note**: For Claude Code versions **2.1.1 and newer**, use the `add-json` command format below. For older versions, see the [legacy command format](#for-older-versions-of-claude-code).
|
||||
>
|
||||
> **Windows / CLI note**: `claude mcp add-json` may return `Invalid input` when adding an HTTP server. If that happens, use the legacy `claude mcp add --transport http ...` command format below.
|
||||
|
||||
1. Run the following command in the terminal (not in Claude Code CLI):
|
||||
```bash
|
||||
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'
|
||||
```
|
||||
|
||||
With an environment variable (Linux/macOS):
|
||||
```bash
|
||||
export GITHUB_PAT="$(grep '^GITHUB_PAT=' .env | cut -d '=' -f2-)"
|
||||
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer '"$GITHUB_PAT"'"}}'
|
||||
```
|
||||
|
||||
With an environment variable (Windows PowerShell):
|
||||
```powershell
|
||||
$githubPatLine = Get-Content .env | Select-String "^\s*GITHUB_PAT\s*=" | Select-Object -First 1
|
||||
$env:GITHUB_PAT = ($githubPatLine.Line -split "=", 2)[1].Trim().Trim('"').Trim("'")
|
||||
claude mcp add-json github "{`"type`":`"http`",`"url`":`"https://api.githubcopilot.com/mcp`",`"headers`":{`"Authorization`":`"Bearer $env:GITHUB_PAT`"}}"
|
||||
```
|
||||
|
||||
> **About the `--scope` flag** (optional): Use this to specify where the configuration is stored:
|
||||
> - `local` (default): Available only to you in the current project (was called `project` in older versions)
|
||||
> - `project`: Shared with everyone in the project via `.mcp.json` file
|
||||
> - `user`: Available to you across all projects (was called `global` in older versions)
|
||||
>
|
||||
> Example: Add `--scope user` to the end of the command to make it available across all projects.
|
||||
|
||||
2. Restart Claude Code
|
||||
3. Run `claude mcp list` to see if the GitHub server is configured
|
||||
|
||||
### Local Server Setup (Docker required)
|
||||
|
||||
### With Docker
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback. Run the following command in the terminal (not in Claude Code CLI):
|
||||
|
||||
```bash
|
||||
claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- docker run -i --rm -p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
1. Run the following command in the terminal (not in Claude Code CLI):
|
||||
```bash
|
||||
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
|
||||
```
|
||||
|
||||
With an environment variable:
|
||||
```bash
|
||||
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$(grep GITHUB_PAT .env | cut -d '=' -f2) -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
|
||||
```
|
||||
2. Restart Claude Code
|
||||
3. Run `claude mcp list` to see if the GitHub server is configured
|
||||
|
||||
### With a Binary (no Docker)
|
||||
|
||||
1. Download [release binary](https://github.com/github/github-mcp-server/releases)
|
||||
2. Add to your `PATH`
|
||||
3. Run:
|
||||
```bash
|
||||
claude mcp add-json github '{"command": "github-mcp-server", "args": ["stdio"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"}}'
|
||||
```
|
||||
2. Restart Claude Code
|
||||
3. Run `claude mcp list` to see if the GitHub server is configured
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
claude mcp list
|
||||
claude mcp get github
|
||||
```
|
||||
|
||||
### For Older Versions of Claude Code
|
||||
|
||||
If you're using Claude Code version **2.1.0 or earlier**, use this legacy command format:
|
||||
|
||||
```bash
|
||||
claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT"
|
||||
```
|
||||
|
||||
With an environment variable:
|
||||
```bash
|
||||
claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer $(grep GITHUB_PAT .env | cut -d '=' -f2)"
|
||||
```
|
||||
|
||||
#### Windows (PowerShell)
|
||||
|
||||
If you see `missing required argument 'name'`, put the server name immediately after `claude mcp add`:
|
||||
|
||||
```powershell
|
||||
$pat = "YOUR_GITHUB_PAT"
|
||||
claude mcp add github --transport http https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer $pat"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Claude Desktop
|
||||
|
||||
> ⚠️ **Note**: Some users have reported compatibility issues with Claude Desktop and Docker-based MCP servers. We're investigating. If you experience issues, try using another MCP host, while we look into it!
|
||||
|
||||
### Prerequisites
|
||||
- Claude Desktop installed (latest version)
|
||||
- [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
|
||||
- [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
> **Note**: Claude Desktop supports MCP servers that are both local (stdio) and remote ("connectors"). Remote servers can generally be added via Settings → Connectors → "Add custom connector". However, the GitHub remote MCP server requires OAuth authentication through a registered GitHub App (or OAuth App), which is not currently supported. Use the local Docker setup instead.
|
||||
|
||||
### Configuration File Location
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
### Local Server Setup (Docker)
|
||||
|
||||
Add this codeblock to your `claude_desktop_config.json`:
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual Setup Steps
|
||||
1. Open Claude Desktop
|
||||
2. Go to Settings → Developer → Edit Config
|
||||
3. Paste the code block above in your configuration file
|
||||
4. If you're navigating to the configuration file outside of the app:
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
5. Open the file in a text editor
|
||||
6. Paste one of the code blocks above, based on your chosen configuration (remote or local)
|
||||
7. Replace `YOUR_GITHUB_PAT` with your actual token or $GITHUB_PAT environment variable
|
||||
8. Save the file
|
||||
9. Restart Claude Desktop
|
||||
|
||||
---
|
||||
|
||||
## Xcode (Claude Agent)
|
||||
|
||||
Xcode's Claude Agent uses the same `.claude.json` configuration format as the Claude Code CLI, but reads it from an Xcode-specific directory rather than the global config location.
|
||||
|
||||
### Configuration File Location
|
||||
|
||||
```
|
||||
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json
|
||||
```
|
||||
|
||||
> Configurations placed here only affect Claude Agent when launched from Xcode. See [Apple's documentation](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments) for more details.
|
||||
|
||||
### Remote Server Setup (Recommended)
|
||||
|
||||
Run the following command in Terminal to add the remote GitHub MCP server:
|
||||
|
||||
```bash
|
||||
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}' --config ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json
|
||||
```
|
||||
|
||||
Or open the file in a text editor and add the `mcpServers` block manually:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Local Server Setup (Docker)
|
||||
|
||||
> **macOS note**: Xcode runs with a minimal `PATH` that typically excludes `/usr/local/bin` (Intel) and `/opt/homebrew/bin` (Apple Silicon). Use the full path to `docker` to ensure it can be found. Run `which docker` in Terminal to find the correct path on your system.
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "/usr/local/bin/docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "/usr/local/bin/docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Setup Steps
|
||||
1. Create or open `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json`
|
||||
2. Add the configuration block above
|
||||
3. Replace `YOUR_GITHUB_PAT` with your actual token
|
||||
4. Restart Xcode
|
||||
|
||||
---
|
||||
|
||||
|
||||
**Authentication Failed:**
|
||||
- Verify PAT has `repo` scope
|
||||
- Check token hasn't expired
|
||||
|
||||
**Remote Server:**
|
||||
- Verify URL: `https://api.githubcopilot.com/mcp`
|
||||
|
||||
**Docker Issues (Local Only):**
|
||||
- Ensure Docker Desktop is running
|
||||
- Try: `docker pull ghcr.io/github/github-mcp-server`
|
||||
- If pull fails: `docker logout ghcr.io` then retry
|
||||
|
||||
**Server Not Starting / Tools Not Showing:**
|
||||
- Run `claude mcp list` to view currently configured MCP servers
|
||||
- Validate JSON syntax
|
||||
- If using an environment variable to store your PAT, make sure you're properly sourcing your PAT using the environment variable
|
||||
- Restart Claude Code and check `/mcp` command
|
||||
- Delete the GitHub server by running `claude mcp remove github` and repeating the setup process with a different method
|
||||
- Make sure you're running Claude Code within the project you're currently working on to ensure the MCP configuration is properly scoped to your project
|
||||
- Check logs:
|
||||
- Claude Code: Use `/mcp` command
|
||||
- Claude Desktop: `ls ~/Library/Logs/Claude/` and `cat ~/Library/Logs/Claude/mcp-server-*.log` (macOS) or `%APPDATA%\Claude\logs\` (Windows)
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
- The npm package `@modelcontextprotocol/server-github` is deprecated as of April 2025
|
||||
- Remote server requires Streamable HTTP support (check your Claude version)
|
||||
- For Claude Code configuration scopes, see the `--scope` flag documentation in the [Remote Server Setup](#remote-server-setup-streamable-http) section
|
||||
@@ -0,0 +1,81 @@
|
||||
# Install GitHub MCP Server in Cline
|
||||
|
||||
[Cline](https://github.com/cline/cline) is an AI coding assistant that runs in VS Code-compatible editors (VS Code, Cursor, Windsurf, etc.). For general setup information (prerequisites, Docker installation, security best practices), see the [Installation Guides README](./README.md).
|
||||
|
||||
## Remote Server
|
||||
|
||||
Cline stores MCP settings in `cline_mcp_settings.json`. To edit it, click the Cline icon in your editor's sidebar, open the menu in the top right corner of the Cline panel, and select **"MCP Servers"**. You can add a remote server through the **"Remote Servers"** tab, or click **"Configure MCP Servers"** to edit the JSON directly.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"type": "streamableHttp",
|
||||
"disabled": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer <YOUR_GITHUB_PAT>"
|
||||
},
|
||||
"autoApprove": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). To customize toolsets, add server-side headers like `X-MCP-Toolsets` or `X-MCP-Readonly` to the `headers` object — see [Server Configuration Guide](../server-configuration.md).
|
||||
|
||||
> **Important:** The transport type must be `"streamableHttp"` (camelCase, no hyphen). Using `"streamable-http"` or omitting the type will cause Cline to fall back to SSE, resulting in a `405` error.
|
||||
|
||||
## Local Server (Docker)
|
||||
|
||||
1. Click the Cline icon in your editor's sidebar (or open the command palette and search for "Cline"), then click the **MCP Servers** icon (server stack icon at the top of the Cline panel), and click **"Configure MCP Servers"** to open `cline_mcp_settings.json`.
|
||||
2. Add one of the configurations below. The OAuth option needs no token; for the PAT option, replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens).
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **SSE error 405 with remote server**: Ensure `"type"` is set to `"streamableHttp"` (camelCase, no hyphen) in `cline_mcp_settings.json`. Using `"streamable-http"` or omitting `"type"` causes Cline to fall back to SSE, which this server does not support.
|
||||
- **Authentication failures**: Verify your PAT has the required scopes
|
||||
- **Docker issues**: Ensure Docker Desktop is installed and running
|
||||
@@ -0,0 +1,134 @@
|
||||
# Install GitHub MCP Server in OpenAI Codex
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. OpenAI Codex (MCP-enabled) installed / available
|
||||
2. A [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
|
||||
|
||||
> The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP.
|
||||
|
||||
## Remote Configuration
|
||||
|
||||
Edit `~/.codex/config.toml` (shared by CLI and IDE extension) and add:
|
||||
|
||||
```toml
|
||||
[mcp_servers.github]
|
||||
url = "https://api.githubcopilot.com/mcp/"
|
||||
# Replace with your real PAT (least-privilege scopes). Do NOT commit this.
|
||||
bearer_token_env_var = "GITHUB_PAT_TOKEN"
|
||||
```
|
||||
|
||||
You can also add it via the Codex CLI:
|
||||
|
||||
```bash
|
||||
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
|
||||
```
|
||||
|
||||
The `--bearer-token-env-var` option is required for PAT-authenticated access to the hosted GitHub MCP server.
|
||||
|
||||
<details>
|
||||
<summary><b>Storing Your PAT Securely</b></summary>
|
||||
<br>
|
||||
|
||||
For security, avoid hardcoding your token. One common approach:
|
||||
|
||||
1. Store your token in `.env` file
|
||||
```
|
||||
GITHUB_PAT_TOKEN=ghp_your_token_here
|
||||
```
|
||||
|
||||
2. Add to .gitignore
|
||||
```bash
|
||||
echo -e ".env" >> .gitignore
|
||||
```
|
||||
</details>
|
||||
|
||||
## Local Docker Configuration
|
||||
|
||||
Use this if you prefer a local, self-hosted instance instead of the remote HTTP server. See the [OpenAI documentation for configuration](https://developers.openai.com/codex/mcp) for the authoritative schema.
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```toml
|
||||
[mcp_servers.github]
|
||||
command = "docker"
|
||||
args = ["run", "-i", "--rm", "-p", "127.0.0.1:8085:8085", "-e", "GITHUB_OAUTH_CALLBACK_PORT", "ghcr.io/github/github-mcp-server"]
|
||||
env = { GITHUB_OAUTH_CALLBACK_PORT = "8085" }
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```toml
|
||||
[mcp_servers.github]
|
||||
command = "docker"
|
||||
args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
|
||||
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here" }
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After starting Codex (CLI or IDE):
|
||||
1. Run `/mcp` in the TUI or use the IDE MCP panel; confirm `github` shows tools.
|
||||
2. Ask: "List my GitHub repositories".
|
||||
3. If tools are missing:
|
||||
- Check token validity & scopes.
|
||||
- Confirm correct table name: `[mcp_servers.github]`.
|
||||
|
||||
## Usage
|
||||
|
||||
After setup, Codex can interact with GitHub directly. It will use the default tool set automatically but can be [configured](../../README.md#default-toolset). Try these example prompts:
|
||||
|
||||
**Repository Operations:**
|
||||
- "List my GitHub repositories"
|
||||
- "Show me recent issues in [owner/repo]"
|
||||
- "Create a new issue in [owner/repo] titled 'Bug: fix login'"
|
||||
|
||||
**Pull Requests:**
|
||||
- "List open pull requests in [owner/repo]"
|
||||
- "Show me the diff for PR #123"
|
||||
- "Add a comment to PR #123: 'LGTM, approved'"
|
||||
|
||||
**Actions & Workflows:**
|
||||
- "Show me recent workflow runs in [owner/repo]"
|
||||
- "Trigger the 'deploy' workflow in [owner/repo]"
|
||||
|
||||
**Gists:**
|
||||
- "Create a gist with this code snippet"
|
||||
- "List my gists"
|
||||
|
||||
> **Tip**: Use `/mcp` in the Codex UI to see all available GitHub tools and their descriptions.
|
||||
|
||||
## Choosing Scopes for Your PAT
|
||||
|
||||
Minimal useful scopes (adjust as needed):
|
||||
- `repo` (general repository operations)
|
||||
- `workflow` (if you want Actions workflow access)
|
||||
- `read:org` (if accessing org-level resources)
|
||||
- `project` (for classic project boards)
|
||||
- `gist` (if using gist tools)
|
||||
|
||||
Use the principle of least privilege: add scopes only when a tool request fails due to permission.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Possible Cause | Fix |
|
||||
|-------|----------------|-----|
|
||||
| Authentication failed | Missing/incorrect PAT scope | Regenerate PAT; ensure `repo` scope present |
|
||||
| 401 Unauthorized (remote) | Token expired/revoked | Create new PAT; update `bearer_token_env_var` |
|
||||
| Server not listed | Wrong table name or syntax error | Use `[mcp_servers.github]`; validate TOML |
|
||||
| Tools missing / zero tools | Insufficient PAT scopes | Add needed scopes (workflow, gist, etc.) |
|
||||
| Token in file risks leakage | Committed accidentally | Rotate token; add file to `.gitignore` |
|
||||
|
||||
## Security Best Practices
|
||||
1. Never commit tokens into version control
|
||||
3. Rotate tokens periodically
|
||||
4. Restrict scopes up front; expand only when required
|
||||
5. Remove unused PATs from your GitHub account
|
||||
|
||||
## References
|
||||
- Remote server URL: `https://api.githubcopilot.com/mcp/`
|
||||
- Release binaries: [GitHub Releases](https://github.com/github/github-mcp-server/releases)
|
||||
- OpenAI Codex MCP docs: https://developers.openai.com/codex/mcp
|
||||
- Main project README: [Advanced configuration options](../../README.md)
|
||||
@@ -0,0 +1,201 @@
|
||||
# Install GitHub MCP Server in Copilot CLI
|
||||
|
||||
The GitHub MCP server comes pre-installed in Copilot CLI, with read-only tools enabled by default.
|
||||
|
||||
## Built-in Server
|
||||
|
||||
To verify the server is available, from an active Copilot CLI session:
|
||||
|
||||
```bash
|
||||
/mcp show github-mcp-server
|
||||
```
|
||||
|
||||
### Per-Session Customization
|
||||
|
||||
Use CLI flags to customize the server for a session:
|
||||
|
||||
```bash
|
||||
# Enable an additional toolset
|
||||
copilot --add-github-mcp-toolset discussions
|
||||
|
||||
# Enable multiple additional toolsets
|
||||
copilot --add-github-mcp-toolset discussions --add-github-mcp-toolset stargazers
|
||||
|
||||
# Enable all toolsets
|
||||
copilot --enable-all-github-mcp-tools
|
||||
|
||||
# Enable a specific tool
|
||||
copilot --add-github-mcp-tool list_discussions
|
||||
|
||||
# Disable the built-in server entirely
|
||||
copilot --disable-builtin-mcps
|
||||
```
|
||||
|
||||
Run `copilot --help` for all available flags. For the list of toolsets, see [Available toolsets](../../README.md#available-toolsets); for the list of tools, see [Tools](../../README.md#tools).
|
||||
|
||||
## Custom Configuration
|
||||
|
||||
You can configure the GitHub MCP server in Copilot CLI using either the interactive command or by manually editing the configuration file.
|
||||
|
||||
> **Server naming:** Name your server `github-mcp-server` to replace the built-in server, or use a different name (e.g., `github`) to run alongside it.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
2. For local server: [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
<details>
|
||||
<summary><b>Storing Your PAT Securely</b></summary>
|
||||
<br>
|
||||
|
||||
To set your PAT as an environment variable:
|
||||
|
||||
```bash
|
||||
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
|
||||
export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Method 1: Interactive Setup (Recommended)
|
||||
|
||||
From an active Copilot CLI session, run the interactive command:
|
||||
|
||||
```bash
|
||||
/mcp add
|
||||
```
|
||||
|
||||
Follow the prompts to configure the server.
|
||||
|
||||
### Method 2: Manual Setup
|
||||
|
||||
Create or edit the configuration file `~/.copilot/mcp-config.json` and add one of the following configurations:
|
||||
|
||||
#### Remote Server
|
||||
|
||||
Connect to the hosted MCP server:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For additional options like toolsets and read-only mode, see the [remote server documentation](../remote-server.md#optional-headers).
|
||||
|
||||
#### Local Docker
|
||||
|
||||
With Docker running, you can run the GitHub MCP server in a container:
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Binary
|
||||
|
||||
You can download the latest binary release from the [GitHub releases page](https://github.com/github/github-mcp-server/releases) or build it from source by running:
|
||||
|
||||
```bash
|
||||
go build -o github-mcp-server ./cmd/github-mcp-server
|
||||
```
|
||||
|
||||
Then configure (replace `/path/to/binary` with the actual path):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "/path/to/binary",
|
||||
"args": ["stdio"],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
1. Restart Copilot CLI
|
||||
2. Run `/mcp show` to list configured servers
|
||||
3. Try: "List my GitHub repositories"
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Local Server Issues
|
||||
|
||||
- **Docker errors**: Ensure Docker Desktop is running
|
||||
- **Image pull failures**: Try `docker logout ghcr.io` then retry
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
- **Invalid PAT**: Verify your GitHub PAT has correct scopes:
|
||||
- `repo` - Repository operations
|
||||
- `read:packages` - Docker image access (if using Docker)
|
||||
- **Token expired**: Generate a new GitHub PAT
|
||||
|
||||
### Configuration Issues
|
||||
|
||||
- **Invalid JSON**: Validate your configuration:
|
||||
```bash
|
||||
cat ~/.copilot/mcp-config.json | jq .
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Copilot CLI Documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli)
|
||||
@@ -0,0 +1,143 @@
|
||||
# Install GitHub MCP Server in Cursor
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Cursor IDE installed (latest version)
|
||||
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
3. For local installation: [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
## Remote Server Setup (Recommended)
|
||||
|
||||
[](https://cursor.com/en/install-mcp?name=github&config=eyJ1cmwiOiJodHRwczovL2FwaS5naXRodWJjb3BpbG90LmNvbS9tY3AvIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfR0lUSFVCX1BBVCJ9fQ%3D%3D)
|
||||
|
||||
Uses GitHub's hosted server at https://api.githubcopilot.com/mcp/. Requires Cursor v0.48.0+ for Streamable HTTP support. While Cursor supports OAuth for some MCP servers, the GitHub server currently requires a Personal Access Token.
|
||||
|
||||
### Install steps
|
||||
|
||||
1. Click the install button above and follow the flow, or go directly to your global MCP configuration file at `~/.cursor/mcp.json` and enter the code block below
|
||||
2. In Tools & Integrations > MCP tools, click the pencil icon next to "github"
|
||||
3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens)
|
||||
4. Save the file
|
||||
5. Restart Cursor
|
||||
|
||||
### Streamable HTTP Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Local Server Setup
|
||||
|
||||
[](https://cursor.com/en/install-mcp?name=github&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtaSAtLXJtIC1lIEdJVEhVQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU4gZ2hjci5pby9naXRodWIvZ2l0aHViLW1jcC1zZXJ2ZXIiLCJlbnYiOnsiR0lUSFVCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IllPVVJfR0lUSFVCX1BBVCJ9fQ%3D%3D)
|
||||
|
||||
The local GitHub MCP server runs via Docker and requires Docker Desktop to be installed and running.
|
||||
|
||||
### Install steps
|
||||
|
||||
1. Click the install button above and follow the flow, or go directly to your global MCP configuration file at `~/.cursor/mcp.json` and enter the code block below
|
||||
2. In Tools & Integrations > MCP tools, click the pencil icon next to "github"
|
||||
3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens)
|
||||
4. Save the file
|
||||
5. Restart Cursor
|
||||
|
||||
### Docker Configuration
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
- **Global (all projects)**: `~/.cursor/mcp.json`
|
||||
- **Project-specific**: `.cursor/mcp.json` in project root
|
||||
|
||||
## Verify Installation
|
||||
|
||||
1. Restart Cursor completely
|
||||
2. Check for green dot in Settings → Tools & Integrations → MCP Tools
|
||||
3. In chat/composer, check "Available Tools"
|
||||
4. Test with: "List my GitHub repositories"
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Remote Server Issues
|
||||
|
||||
- **Streamable HTTP not working**: Ensure you're using Cursor v0.48.0 or later
|
||||
- **Authentication failures**: Verify PAT has correct scopes
|
||||
- **Connection errors**: Check firewall/proxy settings
|
||||
|
||||
### Local Server Issues
|
||||
|
||||
- **Docker errors**: Ensure Docker Desktop is running
|
||||
- **Image pull failures**: Try `docker logout ghcr.io` then retry
|
||||
- **Docker not found**: Install Docker Desktop and ensure it's running
|
||||
|
||||
### General Issues
|
||||
|
||||
- **MCP not loading**: Restart Cursor completely after configuration
|
||||
- **Invalid JSON**: Validate that json format is correct
|
||||
- **Tools not appearing**: Check server shows green dot in MCP settings
|
||||
- **Check logs**: Look for MCP-related errors in Cursor logs
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported)
|
||||
- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional)
|
||||
- **Cursor specifics**: Supports both project and global configurations, uses `mcpServers` key
|
||||
@@ -0,0 +1,200 @@
|
||||
# Install GitHub MCP Server in Google Gemini CLI
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Google Gemini CLI installed (see [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli))
|
||||
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
3. For local installation: [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
<details>
|
||||
<summary><b>Storing Your PAT Securely</b></summary>
|
||||
<br>
|
||||
|
||||
For security, avoid hardcoding your token. Create or update `~/.gemini/.env` (where `~` is your home or project directory) with your PAT:
|
||||
|
||||
```bash
|
||||
# ~/.gemini/.env
|
||||
GITHUB_MCP_PAT=your_token_here
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## GitHub MCP Server Configuration
|
||||
|
||||
MCP servers for Gemini CLI are configured in its settings JSON under an `mcpServers` key.
|
||||
|
||||
- **Global configuration**: `~/.gemini/settings.json` where `~` is your home directory
|
||||
- **Project-specific**: `.gemini/settings.json` in your project directory
|
||||
|
||||
After securely storing your PAT, you can add the GitHub MCP server configuration to your settings file using one of the methods below. You may need to restart the Gemini CLI for changes to take effect.
|
||||
|
||||
> **Note:** For the most up-to-date configuration options, see the [main README.md](../../README.md).
|
||||
|
||||
### Method 1: Gemini Extension (Recommended)
|
||||
|
||||
The simplest way is to use GitHub's hosted MCP server via our gemini extension.
|
||||
|
||||
`gemini extensions install https://github.com/github/github-mcp-server`
|
||||
|
||||
> [!NOTE]
|
||||
> You will still need to have a personal access token with the appropriate scopes called `GITHUB_MCP_PAT` in your environment.
|
||||
|
||||
### Method 2: Remote Server
|
||||
|
||||
You can also connect to the hosted MCP server directly. After securely storing your PAT, configure Gemini CLI with:
|
||||
|
||||
```json
|
||||
// ~/.gemini/settings.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"httpUrl": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer $GITHUB_MCP_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Method 3: Local Docker
|
||||
|
||||
With docker running, you can run the GitHub MCP server in a container.
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
// ~/.gemini/settings.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
// ~/.gemini/settings.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_MCP_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Method 4: Binary
|
||||
|
||||
You can download the latest binary release from the [GitHub releases page](https://github.com/github/github-mcp-server/releases) or build it from source by running `go build -o github-mcp-server ./cmd/github-mcp-server`.
|
||||
|
||||
Then, replacing `/path/to/binary` with the actual path to your binary, configure Gemini CLI with:
|
||||
|
||||
```json
|
||||
// ~/.gemini/settings.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "/path/to/binary",
|
||||
"args": ["stdio"],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_MCP_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To log in with OAuth instead of a PAT (no token to create or store), omit `GITHUB_PERSONAL_ACCESS_TOKEN` — the native binary uses a random loopback callback port, so no extra configuration is needed. See **[Local Server OAuth Login](../oauth-login.md)**.
|
||||
|
||||
## Verification
|
||||
|
||||
To verify that the GitHub MCP server has been configured, start Gemini CLI in your terminal with `gemini`, then:
|
||||
|
||||
1. **Check MCP server status**:
|
||||
|
||||
```
|
||||
/mcp list
|
||||
```
|
||||
|
||||
```
|
||||
ℹConfigured MCP servers:
|
||||
|
||||
🟢 github - Ready (96 tools, 2 prompts)
|
||||
Tools:
|
||||
- github__add_comment_to_pending_review
|
||||
- github__add_issue_comment
|
||||
- github__add_sub_issue
|
||||
...
|
||||
```
|
||||
|
||||
2. **Test with a prompt**
|
||||
```
|
||||
List my GitHub repositories
|
||||
```
|
||||
|
||||
## Additional Configuration
|
||||
|
||||
You can find more MCP configuration options for Gemini CLI here: [MCP Configuration Structure](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html#configuration-structure). For example, bypassing tool confirmations or excluding specific tools.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Local Server Issues
|
||||
|
||||
- **Docker errors**: Ensure Docker Desktop is running
|
||||
```bash
|
||||
docker --version
|
||||
```
|
||||
- **Image pull failures**: Try `docker logout ghcr.io` then retry
|
||||
- **Docker not found**: Install Docker Desktop and ensure it's running
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
- **Invalid PAT**: Verify your GitHub PAT has correct scopes:
|
||||
- `repo` - Repository operations
|
||||
- `read:packages` - Docker image access (if using Docker)
|
||||
- **Token expired**: Generate a new GitHub PAT
|
||||
|
||||
### Configuration Issues
|
||||
|
||||
- **Invalid JSON**: Validate your configuration:
|
||||
```bash
|
||||
cat ~/.gemini/settings.json | jq .
|
||||
```
|
||||
- **MCP connection issues**: Check logs for connection errors:
|
||||
```bash
|
||||
gemini --debug "test command"
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- Gemini CLI Docs > [MCP Configuration Structure](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html#configuration-structure)
|
||||
@@ -0,0 +1,181 @@
|
||||
# Install GitHub MCP Server in OpenCode
|
||||
|
||||
[OpenCode](https://opencode.ai) is a terminal-based AI coding agent that exposes MCP servers under the `mcp` key in `opencode.json` (or `opencode.jsonc`). For general setup information (prerequisites, Docker installation, security best practices), see the [Installation Guides README](./README.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. OpenCode installed (`brew install sst/tap/opencode` or see [OpenCode install docs](https://opencode.ai/docs/))
|
||||
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
3. For local installation: [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The OpenCode docs note that the GitHub MCP server can add a lot of tokens to your context. Consider limiting toolsets — for example, by setting `X-MCP-Toolsets` on the remote server or `--toolsets` on the local server — to keep prompts within your model's context window. See the [Server Configuration Guide](../server-configuration.md) and the [main README's toolsets section](../../README.md#available-toolsets).
|
||||
|
||||
## Remote Server (Recommended)
|
||||
|
||||
Uses GitHub's hosted server at `https://api.githubcopilot.com/mcp/`. Edit your [OpenCode config](https://opencode.ai/docs/config/) (typically `~/.config/opencode/opencode.json`, or `opencode.json` in your project root) and add the following under `mcp`:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"github": {
|
||||
"type": "remote",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"enabled": true,
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). The `oauth: false` setting disables OpenCode's automatic OAuth discovery and tells it to use the PAT in `Authorization` instead — without this, OpenCode may try the OAuth flow first.
|
||||
|
||||
### Using an environment variable for the PAT
|
||||
|
||||
OpenCode supports environment-variable interpolation in config values via `{env:VAR_NAME}`. To avoid putting your PAT directly in `opencode.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"github": {
|
||||
"type": "remote",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"enabled": true,
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer {env:GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Set `GITHUB_PERSONAL_ACCESS_TOKEN` in your shell environment before starting OpenCode.
|
||||
|
||||
## Local Server (Docker)
|
||||
|
||||
The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running.
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"github": {
|
||||
"type": "local",
|
||||
"command": [
|
||||
"docker", "run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"github": {
|
||||
"type": "local",
|
||||
"command": [
|
||||
"docker", "run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> OpenCode expects `command` as a **single array** combining the executable and its arguments (e.g. `["docker", "run", "-i", ...]`), and the env-var key is `environment` (not `env`). This differs from hosts like Zed and Cursor.
|
||||
|
||||
## Verify Installation
|
||||
|
||||
1. Restart OpenCode (or start a new session).
|
||||
2. Check that the server is discovered:
|
||||
```sh
|
||||
opencode mcp list
|
||||
```
|
||||
3. Try a prompt that references the server by name to bias the model toward its tools:
|
||||
```
|
||||
Use the github tool to list my recently merged pull requests.
|
||||
```
|
||||
|
||||
## Managing the Server
|
||||
|
||||
OpenCode exposes a few useful subcommands for MCP servers:
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `opencode mcp list` | List configured MCP servers and their auth/connection status. |
|
||||
| `opencode mcp debug github` | Show auth status, test HTTP connectivity, and walk through OAuth discovery for the `github` server. |
|
||||
| `opencode mcp auth github` | Trigger an OAuth flow manually (only relevant if `oauth` is not set to `false`). |
|
||||
| `opencode mcp logout github` | Clear stored OAuth tokens for the server. |
|
||||
|
||||
## Disabling Tools Per-Agent
|
||||
|
||||
Because the GitHub MCP server can register a large number of tools, you may want to **disable them globally** and **re-enable them only for specific agents**. OpenCode uses the `<server-name>_*` glob pattern to match all tools from a server:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"github": {
|
||||
"type": "remote",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"enabled": true,
|
||||
"oauth": false,
|
||||
"headers": { "Authorization": "Bearer {env:GITHUB_PERSONAL_ACCESS_TOKEN}" }
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"github_*": false
|
||||
},
|
||||
"agent": {
|
||||
"github-helper": {
|
||||
"tools": { "github_*": true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This pattern is recommended by the [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/) for servers with many tools.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **`401 Unauthorized` from the remote server**: confirm your PAT is valid and not expired. If you set `oauth: false`, OpenCode will not attempt an OAuth fallback — the `Authorization` header must be correct.
|
||||
- **Server marked failed in `opencode mcp list`**: run `opencode mcp debug github` to see the exact connectivity and auth diagnostics.
|
||||
- **Tools missing from prompts**: check that `enabled: true` is set on the server and that you have not disabled `github_*` in your `tools` block without re-enabling it for the current agent.
|
||||
- **Context window exceeded**: the GitHub MCP server can register many tools. Use server-side toolset filtering (`X-MCP-Toolsets` header) to register only the toolsets you need.
|
||||
- **Docker errors on the local server**: ensure Docker Desktop is running and the `ghcr.io/github/github-mcp-server` image has been pulled (`docker pull ghcr.io/github/github-mcp-server`).
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Configuration key**: OpenCode uses `mcp` (not `mcpServers` or `context_servers`).
|
||||
- **Type discriminator**: every entry must include `"type": "local"` or `"type": "remote"`.
|
||||
- **Command shape**: `command` is a single array combining the executable and its arguments.
|
||||
- **Environment variable key**: `environment` (not `env`).
|
||||
- **OAuth**: enabled by default for remote servers. Set `"oauth": false` when using PAT-in-`Authorization`, otherwise OpenCode may try OAuth first.
|
||||
- **Env interpolation**: use `{env:VAR_NAME}` in string values to read from the shell environment instead of hard-coding secrets.
|
||||
@@ -0,0 +1,357 @@
|
||||
# Install GitHub MCP Server in Copilot IDEs
|
||||
|
||||
Quick setup guide for the GitHub MCP server in GitHub Copilot across different IDEs. For VS Code instructions, refer to the [VS Code install guide in the README](/README.md#installation-in-vs-code)
|
||||
|
||||
### Requirements:
|
||||
- **GitHub Copilot License**: Any Copilot plan (Free, Pro, Pro+, Business, Enterprise) for Copilot access
|
||||
- **GitHub Account**: Individual GitHub account (organization/enterprise membership optional) for GitHub MCP server access
|
||||
- **MCP Servers in Copilot Policy**: Organizations assigning Copilot seats must enable this policy for all MCP access in Copilot for VS Code and Copilot Coding Agent – all other Copilot IDEs will migrate to this policy in the coming months
|
||||
- **Editor Preview Policy**: Organizations assigning Copilot seats must enable this policy for OAuth access while the Remote GitHub MCP Server is in public preview
|
||||
|
||||
> **Note:** All Copilot IDEs now support the remote GitHub MCP server. VS Code offers OAuth authentication, while Visual Studio, JetBrains IDEs, Xcode, and Eclipse currently use PAT authentication with OAuth support coming soon.
|
||||
|
||||
## Visual Studio
|
||||
|
||||
Requires Visual Studio 2022 version 17.14.9 or later.
|
||||
|
||||
### Remote Server (Recommended)
|
||||
|
||||
The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
|
||||
|
||||
#### Configuration
|
||||
1. Create an `.mcp.json` file in your solution or %USERPROFILE% directory.
|
||||
2. Add this configuration:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
3. Save the file. Wait for CodeLens to update to offer a way to authenticate to the new server, activate that and pick the GitHub account to authenticate with.
|
||||
4. In the GitHub Copilot Chat window, switch to Agent mode.
|
||||
5. Activate the tool picker in the Chat window and enable one or more tools from the "github" MCP server.
|
||||
|
||||
### Local Server
|
||||
|
||||
For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
|
||||
|
||||
#### Configuration
|
||||
1. Create an `.mcp.json` file in your solution or %USERPROFILE% directory.
|
||||
2. Add this configuration. Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"type": "stdio",
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm", "-p", "127.0.0.1:8085:8085", "-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
```json
|
||||
{
|
||||
"inputs": [
|
||||
{
|
||||
"id": "github_pat",
|
||||
"description": "GitHub personal access token",
|
||||
"type": "promptString",
|
||||
"password": true
|
||||
}
|
||||
],
|
||||
"servers": {
|
||||
"github": {
|
||||
"type": "stdio",
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_pat}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
3. Save the file. Wait for CodeLens to update to offer a way to provide user inputs, activate that and paste in a PAT you generate from https://github.com/settings/tokens.
|
||||
4. In the GitHub Copilot Chat window, switch to Agent mode.
|
||||
5. Activate the tool picker in the Chat window and enable one or more tools from the "github" MCP server.
|
||||
|
||||
**Documentation:** [Visual Studio MCP Guide](https://learn.microsoft.com/visualstudio/ide/mcp-servers)
|
||||
|
||||
---
|
||||
|
||||
## JetBrains IDEs
|
||||
|
||||
Agent mode and MCP support available in public preview across IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs.
|
||||
|
||||
### Remote Server (Recommended)
|
||||
|
||||
The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
|
||||
|
||||
> **Note**: OAuth authentication for the remote GitHub server is not yet supported in JetBrains IDEs. You must use a Personal Access Token (PAT).
|
||||
|
||||
#### Configuration Steps
|
||||
1. Install/update the GitHub Copilot plugin
|
||||
2. Click **GitHub Copilot icon in the status bar** → **Edit Settings** → **Model Context Protocol** → **Configure**
|
||||
3. Add configuration:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"requestInit": {
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
4. Press `Ctrl + S` or `Command + S` to save, or close the `mcp.json` file. The configuration should take effect immediately and restart all the MCP servers defined. You can restart the IDE if needed.
|
||||
|
||||
### Local Server
|
||||
|
||||
For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
|
||||
|
||||
#### Configuration
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Documentation:** [JetBrains Copilot Guide](https://plugins.jetbrains.com/plugin/17718-github-copilot)
|
||||
|
||||
---
|
||||
|
||||
## Xcode
|
||||
|
||||
Agent mode and MCP support now available in public preview for Xcode.
|
||||
|
||||
### Remote Server (Recommended)
|
||||
|
||||
The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
|
||||
|
||||
> **Note**: OAuth authentication for the remote GitHub server is not yet supported in Xcode. You must use a Personal Access Token (PAT).
|
||||
|
||||
#### Configuration Steps
|
||||
1. Install/update [GitHub Copilot for Xcode](https://github.com/github/CopilotForXcode)
|
||||
2. Open **GitHub Copilot for Xcode app** → **Agent Mode** → **🛠️ Tool Picker** → **Edit Config**
|
||||
3. Configure your MCP servers:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"requestInit": {
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Local Server
|
||||
|
||||
For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
|
||||
|
||||
#### Configuration
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Documentation:** [Xcode Copilot Guide](https://devblogs.microsoft.com/xcode/github-copilot-exploring-agent-mode-and-mcp-support-in-public-preview-for-xcode/)
|
||||
|
||||
---
|
||||
|
||||
## Eclipse
|
||||
|
||||
MCP support available with Eclipse 2024-03+ and latest version of the GitHub Copilot plugin.
|
||||
|
||||
### Remote Server (Recommended)
|
||||
|
||||
The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
|
||||
|
||||
> **Note**: OAuth authentication for the remote GitHub server is not yet supported in Eclipse. You must use a Personal Access Token (PAT).
|
||||
|
||||
#### Configuration Steps
|
||||
1. Install GitHub Copilot extension from Eclipse Marketplace
|
||||
2. Click the **GitHub Copilot icon** → **Edit Preferences** → **MCP** (under **GitHub Copilot**)
|
||||
3. Add GitHub MCP server configuration:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"requestInit": {
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
4. Click the "Apply and Close" button in the preference dialog and the configuration will take effect automatically.
|
||||
|
||||
### Local Server
|
||||
|
||||
For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
|
||||
|
||||
#### Configuration
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Documentation:** [Eclipse Copilot plugin](https://marketplace.eclipse.org/content/github-copilot)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Personal Access Token
|
||||
|
||||
For PAT authentication, see our [Personal Access Token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for setup instructions.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
After setup:
|
||||
1. Restart your IDE completely
|
||||
2. Open Agent mode in Copilot Chat
|
||||
3. Try: *"List recent issues in this repository"*
|
||||
4. Copilot can now access GitHub data and perform repository operations
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Connection issues**: Verify GitHub PAT permissions and IDE version compatibility
|
||||
- **Authentication errors**: Check if your organization has enabled the MCP policy for Copilot
|
||||
- **Tools not appearing**: Restart IDE after configuration changes and check error logs
|
||||
- **Local server issues**: Ensure Docker is running for Docker-based setups
|
||||
@@ -0,0 +1,83 @@
|
||||
# Install GitHub MCP Server in Roo Code
|
||||
|
||||
[Roo Code](https://github.com/RooCodeInc/Roo-Code) is an AI coding assistant that runs in VS Code-compatible editors (VS Code, Cursor, Windsurf, etc.). For general setup information (prerequisites, Docker installation, security best practices), see the [Installation Guides README](./README.md).
|
||||
|
||||
## Remote Server
|
||||
|
||||
### Step-by-step setup
|
||||
|
||||
1. Click the **Roo Code icon** in your editor's sidebar to open the Roo Code pane
|
||||
2. Click the **gear icon** (⚙️) in the top navigation of the Roo Code pane, then click on **"MCP Servers"** icon on the left.
|
||||
3. Scroll to the bottom and click **"Edit Global MCP"** (for all projects) or **"Edit Project MCP"** (for the current project only)
|
||||
4. Add the configuration below to the opened file (`mcp_settings.json` or `.roo/mcp.json`)
|
||||
5. Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens)
|
||||
6. Save the file — the server should connect automatically
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Important:** The `type` must be `"streamable-http"` (with hyphen). Using `"http"` or omitting the type will fail.
|
||||
|
||||
To customize toolsets, add server-side headers like `X-MCP-Toolsets` or `X-MCP-Readonly` to the `headers` object — see [Server Configuration Guide](../server-configuration.md).
|
||||
|
||||
## Local Server (Docker)
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (replace `YOUR_GITHUB_PAT`; it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Connection failures**: Ensure `type` is `streamable-http`, not `http`
|
||||
- **Authentication failures**: Verify PAT is prefixed with `Bearer ` in the `Authorization` header
|
||||
- **Docker issues**: Ensure Docker Desktop is running
|
||||
@@ -0,0 +1,32 @@
|
||||
# Install GitHub MCP Server in Rovo Dev CLI
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Rovo Dev CLI installed (latest version)
|
||||
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
|
||||
## MCP Server Setup
|
||||
|
||||
Uses GitHub's hosted server at https://api.githubcopilot.com/mcp/.
|
||||
|
||||
### Install steps
|
||||
|
||||
1. Run `acli rovodev mcp` to open the MCP configuration for Rovo Dev CLI
|
||||
2. Add configuration by following example below.
|
||||
3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens)
|
||||
4. Save the file and restart Rovo Dev CLI with `acli rovodev`
|
||||
|
||||
### Example configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,136 @@
|
||||
# Install GitHub MCP Server in Windsurf
|
||||
|
||||
## Prerequisites
|
||||
1. Windsurf IDE installed (latest version)
|
||||
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
3. For local installation: [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
## Remote Server Setup (Recommended)
|
||||
|
||||
The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP protocol. Windsurf currently supports PAT authentication only.
|
||||
|
||||
### Streamable HTTP Configuration
|
||||
Windsurf supports Streamable HTTP servers with a `serverUrl` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"serverUrl": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Local Server Setup
|
||||
|
||||
### Docker Installation (Required)
|
||||
**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-p",
|
||||
"127.0.0.1:8085:8085",
|
||||
"-e",
|
||||
"GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### Via Plugin Store
|
||||
1. Open Windsurf and navigate to Cascade
|
||||
2. Click the **Plugins** icon or **hammer icon** (🔨)
|
||||
3. Search for "GitHub MCP Server"
|
||||
4. Click **Install** and enter your PAT when prompted
|
||||
5. Click **Refresh** (🔄)
|
||||
|
||||
### Manual Configuration
|
||||
1. Click the hammer icon (🔨) in Cascade
|
||||
2. Click **Configure** to open `~/.codeium/windsurf/mcp_config.json`
|
||||
3. Add your chosen configuration from above
|
||||
4. Save the file
|
||||
5. Click **Refresh** (🔄) in the MCP toolbar
|
||||
|
||||
## Configuration Details
|
||||
|
||||
- **File path**: `~/.codeium/windsurf/mcp_config.json`
|
||||
- **Scope**: Global configuration only (no per-project support)
|
||||
- **Format**: Must be valid JSON (use a linter to verify)
|
||||
|
||||
## Verification
|
||||
|
||||
After installation:
|
||||
1. Look for "1 available MCP server" in the MCP toolbar
|
||||
2. Click the hammer icon to see available GitHub tools
|
||||
3. Test with: "List my GitHub repositories"
|
||||
4. Check for green dot next to the server name
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Remote Server Issues
|
||||
- **Authentication failures**: Verify PAT has correct scopes and hasn't expired
|
||||
- **Connection errors**: Check firewall/proxy settings for HTTPS connections
|
||||
- **Streamable HTTP not working**: Ensure you're using the correct `serverUrl` field format
|
||||
|
||||
### Local Server Issues
|
||||
- **Docker errors**: Ensure Docker Desktop is running
|
||||
- **Image pull failures**: Try `docker logout ghcr.io` then retry
|
||||
- **Docker not found**: Install Docker Desktop and ensure it's running
|
||||
|
||||
### General Issues
|
||||
- **Invalid JSON**: Validate with [jsonlint.com](https://jsonlint.com)
|
||||
- **Tools not appearing**: Restart Windsurf completely
|
||||
- **Check logs**: `~/.codeium/windsurf/logs/`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server)
|
||||
- **Remote server URL**: `https://api.githubcopilot.com/mcp/`
|
||||
- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported)
|
||||
- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional)
|
||||
- **Windsurf limitations**: No environment variable interpolation, global config only
|
||||
@@ -0,0 +1,47 @@
|
||||
# Install GitHub MCP Server in Xcode
|
||||
|
||||
Xcode currently supports two built-in coding agents: **Codex** (powered by OpenAI) and **Claude Agent** (powered by Anthropic). Follow the standard installation guide for each agent, with one important difference: Xcode uses its own isolated configuration directories for each agent, separate from your global config.
|
||||
|
||||
> Configurations placed in these directories only affect agents when launched from Xcode. See [Apple's documentation](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments) for more details.
|
||||
|
||||
## Configuration Directories
|
||||
|
||||
| Agent | Configuration Directory |
|
||||
|-------|------------------------|
|
||||
| Codex | `~/Library/Developer/Xcode/CodingAssistant/codex/` |
|
||||
| Claude Agent | `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/` |
|
||||
|
||||
Place your MCP server configuration in the relevant directory above rather than the default location used by the standalone CLI.
|
||||
|
||||
## Setup Guides
|
||||
|
||||
- **[Codex](install-codex.md)** — configure `config.toml` inside `~/Library/Developer/Xcode/CodingAssistant/codex/`
|
||||
- **[Claude Agent](install-claude.md#xcode-claude-agent)** — configure `.claude.json` inside `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/`
|
||||
|
||||
## macOS Path Note
|
||||
|
||||
Xcode runs with a minimal `PATH` that typically excludes common binary locations. If you are using a local STDIO server (e.g. Docker or a pre-built binary), use the **full path** to the command in your config. Run `which docker` (or `which github-mcp-server`) in Terminal to find the correct path on your system. Common locations:
|
||||
|
||||
| Installation | Typical path |
|
||||
|---|---|
|
||||
| Docker (Intel Mac) | `/usr/local/bin/docker` |
|
||||
| Docker (Apple Silicon) | `/usr/local/bin/docker` |
|
||||
| Homebrew (Intel Mac) | `/usr/local/bin/` |
|
||||
| Homebrew (Apple Silicon) | `/opt/homebrew/bin/` |
|
||||
|
||||
> **Logging in with OAuth?** You can run the local server with no PAT — it opens a browser login on first use and keeps the token in memory only. With Docker this needs a fixed callback port published to loopback (`-p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT` with `GITHUB_OAUTH_CALLBACK_PORT=8085`); a native binary uses a random loopback port and needs no extra configuration. See **[Local Server OAuth Login](../oauth-login.md)**.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Possible Cause | Fix |
|
||||
|-------|----------------|-----|
|
||||
| Tools not loading | Config placed in wrong directory | Ensure config is in the Xcode-specific path above, not `~/.codex/` or `~/.claude.json` |
|
||||
| Command not found (STDIO) | Xcode's PATH excludes binary location | Use the full path (e.g. `/usr/local/bin/docker` or `/opt/homebrew/bin/docker`); run `which docker` in Terminal to confirm |
|
||||
| Docker not found | Docker not running | Start Docker Desktop and restart Xcode |
|
||||
| Authentication failed | Invalid or expired PAT | Regenerate PAT and update config |
|
||||
|
||||
## References
|
||||
|
||||
- [Apple Developer Documentation — Setting up coding intelligence](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments)
|
||||
- [Codex MCP documentation](https://developers.openai.com/codex/mcp)
|
||||
- Main project README: [Advanced configuration options](../../README.md)
|
||||
@@ -0,0 +1,128 @@
|
||||
# Install GitHub MCP Server in Zed
|
||||
|
||||
[Zed](https://zed.dev) is a high-performance multiplayer code editor with native MCP support. Zed exposes MCP servers under the `context_servers` settings key. For general setup information (prerequisites, Docker installation, security best practices), see the [Installation Guides README](./README.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Zed installed (latest version — Zed v0.224.0+ recommended for the modern `agent.tool_permissions` settings shape)
|
||||
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
|
||||
3. For local installation: [Docker](https://www.docker.com/) installed and running
|
||||
|
||||
## Installation Methods
|
||||
|
||||
There are two ways to install the GitHub MCP server in Zed:
|
||||
|
||||
- **Option A — Zed Extension (easiest):** a community-maintained [GitHub MCP extension](https://zed.dev/extensions/mcp-server-github) is available in the Zed extension gallery. Install it from the Agent Panel's top-right menu → "View Server Extensions", or from the command palette via the `zed: extensions` action. After installation, Zed pops up a modal asking for your GitHub Personal Access Token.
|
||||
- **Option B — Custom Server (recommended for the official remote endpoint):** add the configuration manually to `settings.json` to use either GitHub's hosted remote server or the official Docker image directly. The rest of this guide covers Option B.
|
||||
|
||||
## Remote Server (Recommended)
|
||||
|
||||
Uses GitHub's hosted server at `https://api.githubcopilot.com/mcp/`. Open your Zed [settings file](https://zed.dev/docs/configuring-zed.html#settings-files) (Command Palette → `zed: open settings`) and add the configuration below under `context_servers`.
|
||||
|
||||
```json
|
||||
{
|
||||
"context_servers": {
|
||||
"github": {
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). To customize toolsets, add server-side headers like `X-MCP-Toolsets` or `X-MCP-Readonly` to the `headers` object — see the [Server Configuration Guide](../server-configuration.md).
|
||||
|
||||
> [!NOTE]
|
||||
> If you omit the `Authorization` header, Zed will attempt the standard MCP OAuth flow on first use. The GitHub MCP server does not currently advertise OAuth for non-Copilot hosts, so a Personal Access Token in the `Authorization` header is the supported path.
|
||||
|
||||
## Local Server (Docker)
|
||||
|
||||
The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running.
|
||||
|
||||
Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
|
||||
|
||||
```json
|
||||
{
|
||||
"context_servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-p", "127.0.0.1:8085:8085",
|
||||
"-e", "GITHUB_OAUTH_CALLBACK_PORT",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_OAUTH_CALLBACK_PORT": "8085"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
|
||||
|
||||
To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
|
||||
|
||||
```json
|
||||
{
|
||||
"context_servers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Zed expects `command` as a **string** plus a separate `args` array, not a single array combining both. This differs from hosts like OpenCode and Claude Desktop.
|
||||
|
||||
## Verify Installation
|
||||
|
||||
1. Open the Agent Panel and click into its Settings view (or run `agent: open settings`).
|
||||
2. Find `github` in the context servers list. A green indicator dot with the tooltip "Server is active" confirms a working configuration. Other colors and tooltip messages indicate startup or auth errors.
|
||||
3. Try a prompt that should invoke a tool — for example, `List my recent GitHub pull requests`. Zed will prompt for tool approval before the first call unless your `agent.tool_permissions.default` is set to `"allow"`.
|
||||
|
||||
## Tool Permissions (Optional)
|
||||
|
||||
Zed v0.224.0+ controls tool approval via `agent.tool_permissions`. Approve a specific GitHub MCP tool without per-call prompts by using the `mcp:<server>:<tool_name>` key format:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"tool_permissions": {
|
||||
"default": "confirm",
|
||||
"rules": [
|
||||
{ "tool": "mcp:github:list_pull_requests", "permission": "allow" },
|
||||
{ "tool": "mcp:github:list_issues", "permission": "allow" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See the [Zed tool permissions docs](https://zed.dev/docs/ai/tool-permissions.html) for the full schema.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Server indicator stays red / "Server is not running"**: check the Agent Panel's settings view for the per-server error string. Most common cause is invalid JSON in `settings.json` — Zed surfaces JSON parse errors in the editor itself.
|
||||
- **`401 Unauthorized`**: verify your PAT has not expired and includes the scopes for the tools you intend to call. The remote endpoint will reject requests with no `Authorization` header (no anonymous access).
|
||||
- **Tools missing from prompts**: confirm the Agent profile in use has not disabled the server. If you're using a [custom profile](https://zed.dev/docs/ai/agent-panel.html#custom-profiles), make sure `enable_all_context_servers` is `true` or that `github` is explicitly listed.
|
||||
- **Docker errors on the local server**: ensure Docker Desktop is running and the `ghcr.io/github/github-mcp-server` image has been pulled at least once. Try `docker pull ghcr.io/github/github-mcp-server` from a terminal.
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Configuration key**: Zed uses `context_servers` (not `mcpServers`).
|
||||
- **Command shape**: `command` is a string + separate `args` array.
|
||||
- **OAuth**: omitting `Authorization` triggers Zed's MCP OAuth flow, but the GitHub MCP server's PAT-based auth is the supported path today.
|
||||
- **External agents**: MCP servers configured in `context_servers` are forwarded to [external agents](https://zed.dev/docs/ai/external-agents.html) via the Agent Client Protocol.
|
||||
Reference in New Issue
Block a user