You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+12-4Lines changed: 12 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -86,7 +86,9 @@ Alternatively, to manually configure VS Code, choose the appropriate JSON block
86
86
-**[Claude Applications](/docs/installation-guides/install-claude.md)** - Installation guide for Claude Desktop and Claude Code CLI
87
87
-**[Codex](/docs/installation-guides/install-codex.md)** - Installation guide for OpenAI Codex
88
88
-**[Cursor](/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE
89
+
-**[OpenCode](/docs/installation-guides/install-opencode.md)** - Installation guide for the OpenCode terminal agent
89
90
-**[Windsurf](/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE
91
+
-**[Zed](/docs/installation-guides/install-zed.md)** - Installation guide for Zed editor
90
92
-**[Rovo Dev CLI](/docs/installation-guides/install-rovo-dev-cli.md)** - Installation guide for Rovo Dev CLI
91
93
92
94
> **Note:** Each MCP host application needs to configure a GitHub App or OAuth App to support remote access via OAuth. Any host application that supports remote MCP servers should support the remote GitHub server with PAT authentication. Configuration details and support levels vary by host. Make sure to refer to the host application's documentation for more info.
@@ -356,7 +358,9 @@ For other MCP host applications, please refer to our installation guides:
356
358
-**[Claude Code & Claude Desktop](docs/installation-guides/install-claude.md)** - Installation guide for Claude Code and Claude Desktop
357
359
-**[Cursor](docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE
358
360
-**[Google Gemini CLI](docs/installation-guides/install-gemini-cli.md)** - Installation guide for Google Gemini CLI
361
+
-**[OpenCode](docs/installation-guides/install-opencode.md)** - Installation guide for the OpenCode terminal agent
359
362
-**[Windsurf](docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE
363
+
-**[Zed](docs/installation-guides/install-zed.md)** - Installation guide for Zed editor
360
364
361
365
For a complete overview of all installation options, see our **[Installation Guides Index](docs/installation-guides)**.
362
366
@@ -1028,22 +1032,26 @@ The following sets of tools are available:
1028
1032
-`project_number`: The project's number. Required for 'list_project_fields', 'list_project_items', and 'list_project_status_updates' methods. (number, optional)
1029
1033
-`query`: Filter/query string. For list_projects: filter by title text and state (e.g. "roadmap is:open"). For list_project_items: advanced filtering using GitHub's project filtering syntax. (string, optional)
1030
1034
1031
-
-**projects_write** - Modify GitHub Project items
1035
+
-**projects_write** - Manage GitHub Projects
1032
1036
-**Required OAuth Scopes**: `project`
1033
1037
-`body`: The body of the status update (markdown). Used for 'create_project_status_update' method. (string, optional)
1038
+
-`field_name`: The name of the iteration field (e.g. 'Sprint'). Required for 'create_iteration_field' method. (string, optional)
1034
1039
-`issue_number`: The issue number (use when item_type is 'issue' for 'add_project_item' method). Provide either issue_number or pull_request_number. (number, optional)
1035
1040
-`item_id`: The project item ID. Required for 'update_project_item' and 'delete_project_item' methods. (number, optional)
1036
1041
-`item_owner`: The owner (user or organization) of the repository containing the issue or pull request. Required for 'add_project_item' method. (string, optional)
1037
1042
-`item_repo`: The name of the repository containing the issue or pull request. Required for 'add_project_item' method. (string, optional)
1038
1043
-`item_type`: The item's type, either issue or pull_request. Required for 'add_project_item' method. (string, optional)
1044
+
-`iteration_duration`: Duration in days for iterations of the field (e.g. 7 for weekly, 14 for bi-weekly). Required for 'create_iteration_field' method. (number, optional)
1045
+
-`iterations`: Custom iterations for 'create_iteration_field' method. Only set this when you need iterations with varying durations, breaks between them, or specific titles. Otherwise omit it: GitHub auto-creates three iterations of 'iteration_duration' days starting on 'start_date', which is the right choice for most cases. (object[], optional)
1039
1046
-`method`: The method to execute (string, required)
1040
1047
-`owner`: The project owner (user or organization login). The name is not case sensitive. (string, required)
1041
-
-`owner_type`: Owner type (user or org). If not provided, will be automatically detected. (string, optional)
1042
-
-`project_number`: The project's number. (number, required)
1048
+
-`owner_type`: Owner type (user or org). Required for 'create_project' method. If not provided for other methods, will be automatically detected. (string, optional)
1049
+
-`project_number`: The project's number. Required for all methods except 'create_project'. (number, optional)
1043
1050
-`pull_request_number`: The pull request number (use when item_type is 'pull_request' for 'add_project_item' method). Provide either issue_number or pull_request_number. (number, optional)
1044
-
-`start_date`: The start date of the status update in YYYY-MM-DD format. Used for 'create_project_status_update' method. (string, optional)
1051
+
-`start_date`: Start date in YYYY-MM-DD format. Used for 'create_project_status_update' and 'create_iteration_field' methods. (string, optional)
1045
1052
-`status`: The status of the project. Used for 'create_project_status_update' method. (string, optional)
1046
1053
-`target_date`: The target date of the status update in YYYY-MM-DD format. Used for 'create_project_status_update' method. (string, optional)
1054
+
-`title`: The project title. Required for 'create_project' method. (string, optional)
1047
1055
-`updated_field`: Object consisting of the ID of the project field to update and the new value for the field. To clear the field, set value to null. Example: {"id": 123456, "value": "New Value"}. Required for 'update_project_item' method. (object, optional)
[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).
4
+
5
+
## Prerequisites
6
+
7
+
1. OpenCode installed (`brew install sst/tap/opencode` or see [OpenCode install docs](https://opencode.ai/docs/))
8
+
2.[GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
9
+
3. For local installation: [Docker](https://www.docker.com/) installed and running
10
+
11
+
> [!IMPORTANT]
12
+
> 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).
13
+
14
+
## Remote Server (Recommended)
15
+
16
+
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`:
17
+
18
+
```json
19
+
{
20
+
"$schema": "https://opencode.ai/config.json",
21
+
"mcp": {
22
+
"github": {
23
+
"type": "remote",
24
+
"url": "https://api.githubcopilot.com/mcp/",
25
+
"enabled": true,
26
+
"oauth": false,
27
+
"headers": {
28
+
"Authorization": "Bearer YOUR_GITHUB_PAT"
29
+
}
30
+
}
31
+
}
32
+
}
33
+
```
34
+
35
+
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.
36
+
37
+
### Using an environment variable for the PAT
38
+
39
+
OpenCode supports environment-variable interpolation in config values via `{env:VAR_NAME}`. To avoid putting your PAT directly in `opencode.json`:
Set `GITHUB_PERSONAL_ACCESS_TOKEN` in your shell environment before starting OpenCode.
59
+
60
+
## Local Server (Docker)
61
+
62
+
The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running.
63
+
64
+
```json
65
+
{
66
+
"$schema": "https://opencode.ai/config.json",
67
+
"mcp": {
68
+
"github": {
69
+
"type": "local",
70
+
"command": [
71
+
"docker", "run", "-i", "--rm",
72
+
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
73
+
"ghcr.io/github/github-mcp-server"
74
+
],
75
+
"enabled": true,
76
+
"environment": {
77
+
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
78
+
}
79
+
}
80
+
}
81
+
}
82
+
```
83
+
84
+
> [!IMPORTANT]
85
+
> 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.
86
+
87
+
## Verify Installation
88
+
89
+
1. Restart OpenCode (or start a new session).
90
+
2. Check that the server is discovered:
91
+
```sh
92
+
opencode mcp list
93
+
```
94
+
3. Try a prompt that references the server by name to bias the model toward its tools:
95
+
```
96
+
Use the github tool to list my recently merged pull requests.
97
+
```
98
+
99
+
## Managing the Server
100
+
101
+
OpenCode exposes a few useful subcommands for MCP servers:
102
+
103
+
| Command | Purpose |
104
+
| --- | --- |
105
+
|`opencode mcp list`| List configured MCP servers and their auth/connection status. |
106
+
|`opencode mcp debug github`| Show auth status, test HTTP connectivity, and walk through OAuth discovery for the `github` server. |
107
+
|`opencode mcp auth github`| Trigger an OAuth flow manually (only relevant if `oauth` is not set to `false`). |
108
+
|`opencode mcp logout github`| Clear stored OAuth tokens for the server. |
109
+
110
+
## Disabling Tools Per-Agent
111
+
112
+
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:
This pattern is recommended by the [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/) for servers with many tools.
138
+
139
+
## Troubleshooting
140
+
141
+
-**`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.
142
+
-**Server marked failed in `opencode mcp list`**: run `opencode mcp debug github` to see the exact connectivity and auth diagnostics.
143
+
-**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.
144
+
-**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.
145
+
-**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`).
146
+
147
+
## Important Notes
148
+
149
+
-**Configuration key**: OpenCode uses `mcp` (not `mcpServers` or `context_servers`).
150
+
-**Type discriminator**: every entry must include `"type": "local"` or `"type": "remote"`.
151
+
-**Command shape**: `command` is a single array combining the executable and its arguments.
0 commit comments