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"

1. Set Repository permissions:

• Administration: Read and write ✅
• Contents: Read-only ✅

1. 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