Skip to content

Commit 254b4a3

Browse files
D1M1TR10SD1M1TR10S
authored
Update installation guide for GitHub MCP Server in Windsurf...
...including prerequisites, installation steps, and security best practices.
1 parent e3b3460 commit 254b4a3

1 file changed

Lines changed: 106 additions & 40 deletions

File tree

‎docs/installation-guides/install-windsurf.md‎

Lines changed: 106 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,37 @@
11
# Install GitHub MCP Server in Windsurf
22

33
## Prerequisites
4+
1. Windsurf IDE installed (latest version)
5+
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
6+
3. For local installation: [Docker](https://www.docker.com/) installed and running
47

5-
1. Windsurf IDE installed
6-
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
7-
3. [Docker](https://www.docker.com/) installed and running
8+
## Remote Server Setup (Recommended)
89

9-
## Installation Steps
10-
11-
### Option 1: Plugin Installation (Recommended)
10+
The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports both HTTP and SSE protocols. Windsurf currently supports PAT authentication only.
1211

13-
1. Click the `Plugins` icon or the MCP hammer icon in the Cascade window
14-
2. Search for and select the `GitHub MCP Server`
15-
3. Click `Install` at the top of the page
16-
4. Input your GitHub PAT token in the input field when prompted
17-
5. Click `Refresh` on the plugin page and restart Windsurf, if needed
12+
### Direct SSE Configuration
13+
Windsurf supports SSE servers with a `serverUrl` field:
1814

19-
### Option 2: Manual Configuration
15+
```json
16+
{
17+
"mcpServers": {
18+
"github": {
19+
"serverUrl": "https://api.githubcopilot.com/mcp/",
20+
"headers": {
21+
"Authorization": "Bearer YOUR_GITHUB_PAT"
22+
}
23+
}
24+
}
25+
}
26+
```
2027

21-
If you prefer manual configuration, the installation will create a configuration file at `~/.codeium/windsurf/mcp_config.json` that looks like this:
28+
## Local Server Setup
2229

30+
### Option 1: Docker (Recommended)
2331
```json
2432
{
2533
"mcpServers": {
26-
"github-mcp-server": {
34+
"github": {
2735
"command": "docker",
2836
"args": [
2937
"run",
@@ -34,46 +42,104 @@ If you prefer manual configuration, the installation will create a configuration
3442
"ghcr.io/github/github-mcp-server"
3543
],
3644
"env": {
37-
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"
45+
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
3846
}
3947
}
4048
}
4149
}
4250
```
4351

44-
## Important Security Notes
52+
### Option 2: NPX
53+
```json
54+
{
55+
"mcpServers": {
56+
"github": {
57+
"command": "npx",
58+
"args": ["-y", "@modelcontextprotocol/server-github"],
59+
"env": {
60+
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
61+
}
62+
}
63+
}
64+
}
65+
```
66+
67+
**Note**: The npm package has a deprecation notice but remains functional.
4568

46-
⚠️ **Environment Variable Limitations**: Environment-variable interpolation (using a `$GITHUB_PAT` variable) is not supported in Windsurf.
69+
## Installation Steps
70+
71+
### Via Plugin Store
72+
1. Open Windsurf and navigate to Cascade
73+
2. Click the **Plugins** icon or **hammer icon** (🔨)
74+
3. Search for "GitHub MCP Server"
75+
4. Click **Install** and enter your PAT when prompted
76+
5. Click **Refresh** (🔄)
4777

48-
### Security Best Practices
78+
### Manual Configuration
79+
1. Click the hammer icon (🔨) in Cascade
80+
2. Click **Configure** to open `~/.codeium/windsurf/mcp_config.json`
81+
3. Add your chosen configuration from above
82+
4. Save the file
83+
5. Click **Refresh** (🔄) in the MCP toolbar
4984

50-
- **File Permissions**: Lock down file permissions for the configuration file:
51-
```bash
52-
chmod 600 ~/.codeium/windsurf/mcp_config.json
53-
```
54-
- **Version Control**: Avoid committing configuration files with tokens to version control
55-
- **Token Scope**: Limit PAT scopes to necessary repositories and tools only
56-
- **Token Rotation**: Regularly rotate your GitHub Personal Access Tokens
85+
## Security Best Practices
5786

58-
## Configuration File Location
87+
### Critical Security Note
88+
⚠️ **Windsurf does NOT support environment variable interpolation**. You must hardcode your PAT in the configuration file. This makes security practices crucial.
5989

60-
The MCP configuration is stored at:
61-
- `~/.codeium/windsurf/mcp_config.json`
90+
### File Protection
91+
```bash
92+
# Secure the configuration file
93+
chmod 600 ~/.codeium/windsurf/mcp_config.json
94+
95+
# Verify permissions
96+
ls -la ~/.codeium/windsurf/mcp_config.json
97+
```
6298

63-
## Post-Installation
99+
### Token Security
100+
- Create PATs with minimum required scopes:
101+
- `repo` - For repository operations
102+
- `read:packages` - For Docker image pull (local setup)
103+
- Additional scopes based on tools you need
104+
- Use separate PATs for different projects
105+
- Regularly rotate tokens
106+
- Never commit configuration files to version control
107+
108+
## Configuration Details
109+
110+
- **File path**: `~/.codeium/windsurf/mcp_config.json`
111+
- **Scope**: Global configuration only (no per-project support)
112+
- **Format**: Must be valid JSON (use a linter to verify)
113+
114+
## Verification
64115

65116
After installation:
66-
1. Restart Windsurf if prompted
67-
2. The GitHub MCP Server should be available in the MCP tools
68-
3. You can verify the installation by checking the plugins page
117+
1. Look for "1 available MCP server" in the MCP toolbar
118+
2. Click the hammer icon to see available GitHub tools
119+
3. Test with: "List my GitHub repositories"
120+
4. Check for green dot next to the server name
69121

70122
## Troubleshooting
71123

72-
- Ensure Docker is running and accessible
73-
- Verify your GitHub PAT is valid and has required permissions
74-
- Check that the JSON configuration is valid
75-
- Restart Windsurf after making configuration changes
76-
- Review Windsurf logs for any MCP server startup errors
77-
- Ensure the GitHub MCP Server Docker image is accessible (`ghcr.io/github/github-mcp-server`)
78-
- Try refreshing the plugins page if the server doesn't appear
79-
- Check that your internet connection allows Docker image pulls from GitHub Container Registry
124+
### Remote Server Issues
125+
- **Authentication failures**: Verify PAT has correct scopes and hasn't expired
126+
- **Connection errors**: Check firewall/proxy settings for HTTPS connections
127+
- **SSE not working**: Ensure you're using the correct `serverUrl` field format
128+
129+
### Local Server Issues
130+
- **Docker errors**: Ensure Docker Desktop is running
131+
- **Image pull failures**: Try `docker logout ghcr.io` then retry
132+
- **NPX failures**: Clear npm cache with `npm cache clean --force`
133+
134+
### General Issues
135+
- **Invalid JSON**: Validate with [jsonlint.com](https://jsonlint.com)
136+
- **Tools not appearing**: Restart Windsurf completely
137+
- **Check logs**: `~/.codeium/windsurf/logs/`
138+
139+
## Important Notes
140+
141+
- **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server)
142+
- **Remote server URL**: `https://api.githubcopilot.com/mcp/`
143+
- **Docker image**: `ghcr.io/github/github-mcp-server`
144+
- **npm package**: `@modelcontextprotocol/server-github` (deprecated but functional)
145+
- **Windsurf limitations**: No environment variable interpolation, global config only

0 commit comments

Comments
 (0)