@dragons-claw/mcp-github

A Model Context Protocol (MCP) server for GitHub operations. Provides high-level, verified GitHub workflows via git/gh CLI.

Features

• Clone & Branch: Clone repositories and create feature branches
• Full Contribution: Complete PR workflow in one command (clone → branch → edit → commit → push → PR)
• Issue Management: Create issues with duplicate checking
• PR Management: Create PRs with branch verification
• Commit & Push: Stage, commit, and push changes
• Workspace Cleanup: Remove cloned repositories

All operations include:

• Step-by-step verification
• Windows/PowerShell compatibility
• Intelligent stderr handling (git/gh write progress to stderr)
• Existing resource detection (reuse clones, skip existing PRs)

Installation

npm install @dragons-claw/mcp-github

Or run directly:

npx @dragons-claw/mcp-github

Requirements

• Node.js 18+
• Git CLI installed and configured
• GitHub CLI (gh) installed and authenticated (gh auth login)

Usage

As MCP Server (stdio mode)

For integration with MCP clients like Claude Desktop:

mcp-github --stdio --workspace /path/to/workspace

Add to Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@dragons-claw/mcp-github", "--stdio", "--workspace", "/path/to/workspace"]
    }
  }
}

As CLI Tool

# List all available tools
mcp-github

# Clone and create branch
mcp-github --tool github_clone_and_branch \
  --repo owner/repo \
  --branch feature-name

# Full contribution workflow
mcp-github --tool github_full_contribution \
  --repo owner/repo \
  --branch feature-name \
  --filePath src/new-file.ts \
  --fileContent "console.log('hello');" \
  --commitMessage "Add new file" \
  --prTitle "Add new feature"

# Create issue
mcp-github --tool github_create_issue \
  --repo owner/repo \
  --title "Bug report" \
  --body "Description of the issue"

As Library

import { MCPGitHubServer, initMCPGitHubServer } from '@dragons-claw/mcp-github';

const server = initMCPGitHubServer({
  workspacePath: '/path/to/workspace',
});

await server.start();

// Execute a tool
const result = await server.executeTool('github_clone_and_branch', {
  repo: 'owner/repo',
  branch: 'feature-name',
});

console.log(result.success ? result.content : result.error);

Available Tools

Tool	Description
github_clone_and_branch	Clone a repo and create/checkout a branch
github_full_contribution	Complete PR workflow: clone, branch, edit, commit, push, create PR
github_create_issue	Create a GitHub issue
github_create_pr	Create a pull request (requires branch pushed first)
github_commit_and_push	Stage, commit, and push changes
github_get_checklist	Get status of a task checklist
github_list_active_tasks	List all in-progress tasks
github_cleanup_workspace	Remove a cloned repository

Environment Variables

Variable	Description	Default
MCP_WORKSPACE	Default workspace directory	Current directory
DEBUG	Enable debug logging	false

License

MIT

Contributing

See SKILLS.md for workflow documentation and best practices.