Github Ruleset MCP
An MCP server that lets Claude (or any MCP client) manage GitHub branch protection rulesets programmatically.
Ask AI about Github Ruleset MCP
Powered by Claude · Grounded in docs
I know everything about Github Ruleset MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
github-ruleset-mcp
Branch protection as code. 4 templates, 5 tools, 2-minute setup.
An MCP server that lets Claude (or any MCP client) manage GitHub branch protection rulesets programmatically.
Why?
Setting up branch protection manually is tedious. This MCP server lets you say:
Protect myorg/api with standard rules
And Claude handles the rest—validating, previewing, and applying the ruleset via GitHub's API.
Installation
Prerequisites
- Node.js 18.0.0 or higher
- npm or yarn
- GitHub Personal Access Token with appropriate scopes
1. Clone and Build
git clone https://github.com/wilsonhj/github-ruleset-mcp.git
cd github-ruleset-mcp
npm install
npm run build
2. Configure GitHub Token
Choose one of these secure methods:
Option A: Environment Variable (Recommended)
Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):
export GITHUB_TOKEN="ghp_your_token_here"
Then reload: source ~/.zshrc
Option B: macOS Keychain (Most Secure)
# Store token in Keychain
security add-generic-password -a "$USER" -s "github_personal_access_token" -w "ghp_your_token_here"
# Add to ~/.zshrc
echo 'export GITHUB_TOKEN=$(security find-generic-password -a "$USER" -s "github_personal_access_token" -w 2>/dev/null)' >> ~/.zshrc
source ~/.zshrc
3. Add to Claude Desktop
Edit your Claude Desktop config:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/claude/claude_desktop_config.json
{
"mcpServers": {
"github-ruleset": {
"command": "node",
"args": ["/absolute/path/to/github-ruleset-mcp/dist/index.js"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
Important: Replace /absolute/path/to/github-ruleset-mcp with the actual path.
4. Restart Claude Desktop
Close and reopen Claude Desktop to load the MCP server.
5. Verify Installation
Ask Claude: "List available GitHub ruleset templates"
If you see 4 templates (standard, strict, relaxed, controlled), it's working! ✅
Testing (Optional)
Test the server before adding to Claude Desktop:
# Install MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
This opens a web UI where you can interactively test all 5 tools.
Templates
| Template | When to Use | What It Does |
|---|---|---|
standard | Most repos | 1 approval, CI required, no force push |
strict | Production | 2 approvals, signed commits, code scanning |
relaxed | Dev branches | PR required, no approval needed |
controlled | Releases | Team-gated, staging deploy required |
Tools
| Tool | Description |
|---|---|
apply_ruleset | Apply branch protection (dry-run by default) |
check_protection | Verify a branch is protected |
list_rulesets | Show all rulesets in a repo |
delete_ruleset | Remove a ruleset (requires confirmation) |
list_templates | Show available templates |
Examples
Protect a new repo:
Apply standard branch protection to myorg/new-service
Pre-deployment check:
Verify myorg/api has branch protection before I deploy
Custom ruleset:
Protect myorg/api main branch requiring 3 approvals and signed commits
Token Scopes
Creating a Fine-Grained Token (Recommended)
- Go to https://github.com/settings/tokens?type=beta
- Click "Generate new token"
- Configure:
- Token name:
github-ruleset-mcp - Expiration: 90 days (or custom)
- Repository access: "Only select repositories" or "All repositories"
- Token name:
- Set Repository permissions:
- Administration: Read and write ✅
- Contents: Read-only ✅
- Generate and copy the token immediately
Classic Token (Alternative)
If using classic tokens, you need:
repo— Full repository accessadmin:org_hook— Organization ruleset access (if managing org-level rulesets)
Troubleshooting
"GITHUB_TOKEN environment variable is required"
The token isn't set in your environment. Verify:
echo $GITHUB_TOKEN
If empty, check that:
- You added the token to your shell profile (
~/.zshrc) - You ran
source ~/.zshrcto reload - Claude Desktop was restarted after setting the token
"GraphQL: Could not resolve to a Repository"
Check that:
- Repository owner/name are correct
- Your token has access to the repository
- The repository exists
MCP Server Not Showing in Claude Desktop
- Verify the config file path is correct
- Check the
argspath points to the compileddist/index.js - Restart Claude Desktop completely (quit and reopen)
- Check Claude Desktop logs for errors
Tools Execute But Nothing Happens
If using apply_ruleset, remember it defaults to dry-run mode. Set dry_run: false to actually apply changes.
Advanced
See docs/ADVANCED.md for:
- Custom ruleset JSON
- Multi-agent integration
- CI/CD pipeline integration
Contributing
PRs welcome! Please open an issue first for major changes.
License
MIT
