Cross-platform NPX-wrappable GitHub MCP Server
npm install github-mcp-customA custom-packaged version of the GitHub MCP Server that runs seamlessly on Windows, Linux, and macOS via npx. This wraps the Go binary in a Node.js launcher so developers using Claude Desktop can use GitHub MCP capabilities with no Docker or manual compilation required.
---
The official GitHub MCP Server requires:
- Docker or
- Manual Go compilation.
These options work well on Linux/macOS, but break or complicate Windows usage.
This package makes the server available via npx, eliminating the need for:
- Docker
- Go installation
- Custom PATH setups
---
- Provides a cross-platform github-mcp-custom command
- Executes the prebuilt Go binary via Node.js wrapper
- Fully NPX-compatible on all OSes
- Works out-of-the-box with Claude Desktop or other MCP-compatible tools
- Protocol version compatible with Claude Desktop
---
``bash`
npx -y github-mcp-custom@1.0.20 stdio
> First-time use will download the package and run it automatically.
`bash`
npm install -g github-mcp-custom@1.0.20
github-mcp-custom stdio
If NPX has issues on Windows, use the direct path:
`json`
{
"mcpServers": {
"github": {
"command": "C:\\Users\\[USERNAME]\\AppData\\Roaming\\npm\\node_modules\\github-mcp-custom\\dist\\github-mcp-server.exe",
"args": ["stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
}
}
}
}
Replace [USERNAME] with your actual Windows username.
Note: Use @1.0.20 or later for optimal Claude Desktop compatibility.
---
- Node.js v14 or later must be installed
- An active GitHub Personal Access Token with proper scopes:
- repo (for repository access)read:org
- (for organization access)user
- (for user information)
---
1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select these scopes:
- ✅ repo - Full control of private repositoriesread:org
- ✅ - Read org and team membershipuser
- ✅ - Update user data
4. Copy the generated token
---
Add this to your Claude Desktop configuration file located at:
%APPDATA%\Claude\claude_desktop_config.json
`json`
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "github-mcp-custom@1.0.20", "stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
}
}
}
}
Add this to your Claude Desktop configuration file located at:
~/Library/Application Support/Claude/claude_desktop_config.json
`json`
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "github-mcp-custom@1.0.20", "stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
}
}
}
}
Add this to your Claude Desktop configuration file located at:
~/.config/Claude/claude_desktop_config.json
`json`
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "github-mcp-custom@1.0.20", "stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
}
}
}
}
If you've installed globally, you can use:
`json`
{
"mcpServers": {
"github": {
"command": "github-mcp-custom",
"args": ["stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
}
}
}
}
---
Once configured, you'll have access to these GitHub MCP tools:
- Search GitHub repositories
- get_file_contents - Read file contents from repos
- create_or_update_file - Create/modify files
- create_repository - Create new repositories
- fork_repository - Fork repositories
- create_branch - Create branches
- push_files - Push file changes
- list_commits - View commit history
- get_commit - Get specific commit details$3
- get_issue - Get issue details with timestamps
- create_issue - Create new issues
- update_issue - Update issues (returns updated info with timestamps)
- search_issues - Search across issues
- list_issues - List repository issues
- get_issue_comments - Get issue comments with timestamps
- add_issue_comment - Add comments to issues$3
- get_pull_request - Get PR details
- create_pull_request - Create new PRs
- update_pull_request - Update existing PRs
- merge_pull_request - Merge PRs
- get_pull_request_files - See PR changes
- get_pull_request_comments - Get PR comments
- create_and_submit_pull_request_review - Review PRs$3
- list_code_scanning_alerts - Code security alerts
- list_secret_scanning_alerts - Secret scanning alerts$3
- list_notifications - Get notifications
- dismiss_notification - Dismiss notifications
- mark_all_notifications_read - Mark all as read$3
- get_me - Get authenticated user details
- search_users - Search GitHub users---
🧪 Testing Your Setup
1. Test the command directly:
`bash
npx -y github-mcp-custom@1.0.20 stdio
`
Should output: 2. Test with Claude Desktop:
- Restart Claude Desktop after updating the config
- Try asking: "Can you get my GitHub user information?"
- Claude should be able to use the
tool---
🔧 Troubleshooting
$3
❌ "Server disconnected" in Claude Desktop
- Ensure you're using version
1.0.20 or later
- Check that your GitHub token is valid and has proper scopes
- Verify the JSON configuration is valid (no trailing commas)❌ "Command not found"
- Make sure Node.js is installed and in your PATH
- Try running
npm --version to verify npm is working❌ "Authentication failed"
- Verify your GitHub Personal Access Token is correct
- Check that the token has the required scopes (
repo, read:org, user)
- Make sure the token hasn't expired❌ "Method not found" errors
- Update to the latest version:
npm install -g github-mcp-custom@latest---
📁 File Structure
github-mcp-custom/
├── bin/
│ └── index.js # Node.js launcher
├── dist/
│ ├── github-mcp-server.exe # Windows binary
│ ├── github-mcp-server-macos # macOS binary
│ └── github-mcp-server-linux # Linux binary
├── package.json
└── README.md
---
🖥️ Platform Compatibility
| Platform | Tested | Notes |
|------------------|--------|--------------------------|
| ✅ Windows 10/11 | ✔️ | No Docker or Go needed |
| ✅ Linux (Ubuntu) | ✔️ | Works out-of-the-box |
| ✅ macOS (Intel/M1) | ✔️ | Works with NPX easily |
---
📈 Version History
- v1.0.20 - Fixed Claude Desktop protocol compatibility
- v1.0.16 - Previous version (had connection issues)
- v1.0.x - Earlier releases
---
👷 How This Was Built
1. Cloned the official GitHub MCP Server repository.
2. Updated protocol version for Claude Desktop compatibility.
3. Compiled Go binaries for all platforms:
bash
GOOS=linux GOARCH=amd64 go build -o dist/github-mcp-server-linux ./cmd/github-mcp-server
GOOS=darwin GOARCH=amd64 go build -o dist/github-mcp-server-macos ./cmd/github-mcp-server
GOOS=windows GOARCH=amd64 go build -o dist/github-mcp-server.exe ./cmd/github-mcp-server
`
4. Created a Node.js wrapper script () for cross-platform execution.
5. Set up NPM-compatible package.json` with proper bin configuration.---
Contributions are welcome! Please visit our GitHub repository:
🔗 Repository: https://github.com/idletoaster/github-mcp-custom
- 🐛 Report issues: GitHub Issues
- 💡 Feature requests: GitHub Discussions
- 🔧 Pull requests: Contribution Guidelines
---
MIT License
Copyright (c) 2025 idletoaster
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.