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)

1. Go to https://github.com/settings/tokens?type=beta
2. Click "Generate new token"
3. Configure:
   • Token name: github-ruleset-mcp
   • Expiration: 90 days (or custom)
   • Repository access: "Only select repositories" or "All repositories"
4. Set Repository permissions:
   • Administration: Read and write ✅
   • Contents: Read-only ✅
5. Generate and copy the token immediately

Classic Token (Alternative)

If using classic tokens, you need:

• repo — Full repository access
• admin: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:

1. You added the token to your shell profile (~/.zshrc)
2. You ran source ~/.zshrc to reload
3. Claude Desktop was restarted after setting the token

"GraphQL: Could not resolve to a Repository"

Check that:

1. Repository owner/name are correct
2. Your token has access to the repository
3. The repository exists

MCP Server Not Showing in Claude Desktop

1. Verify the config file path is correct
2. Check the args path points to the compiled dist/index.js
3. Restart Claude Desktop completely (quit and reopen)
4. 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