-
Notifications
You must be signed in to change notification settings - Fork 4.3k
docs: add installation guides for Zed and OpenCode #2535
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jluocsa
wants to merge
1
commit into
github:main
Choose a base branch
from
jluocsa:docs/install-zed-and-opencode
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+265
−0
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,154 @@ | ||
| # 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. | ||
|
|
||
| ```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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| # 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. | ||
|
|
||
| ```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. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not just use
opencode mcp addas mentioned in https://opencode.ai/docs/cli/#mcp ?After all, https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md prefers to use
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'.