# GitHub MCP Server

**Connect Claude directly to your GitHub repositories as an intelligent copilot for code changes, commits, and PRs.**

Use Claude to:
- ✅ Read & explore code
- ✅ Update files with auto-commits
- ✅ Create branches & manage PRs
- ✅ Commit multiple files at once
- ✅ Search & analyze code patterns
- ✅ All with proper git messages & co-author attribution

Works anywhere: **Claude Desktop** → **Web Dashboard** → **Mobile** → **Local VPS**

---

## 🎯 What This Does

### Before (Manual)
```
"Claude, how do I fix this error?"
→ Claude explains in chat
→ You manually edit files
→ You manually commit & push
```

### After (GitHub MCP)
```
"Claude, fix the MACD signal calculation and commit"
→ Claude reads the code
→ Makes the fix
→ Commits with a proper message
→ Shows you the commit link
```

---

## 🚀 Quick Start

### 1. One-Time Setup (5 min)

```bash
# Clone the MCP server
git clone https://github.com/techybiky/github-mcp.git
cd github-mcp

# Install dependencies
npm install

# Build for production
npm run build
```

### 2. Get GitHub Token

1. Go to https://github.com/settings/tokens/new
2. Create "Personal Access Token (Classic)"
3. Select scopes: `repo`, `read:user`, `workflow`
4. Copy the token (you won't see it again)

### 3. Configure Claude Desktop

**macOS/Linux:**
```bash
cat > ~/.config/Claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_paste_your_token",
        "GITHUB_OWNER": "techybiky",
        "GITHUB_REPO": "niftybot"
      }
    }
  }
}
EOF
```

**Windows:**
Create `%APPDATA%\Claude\claude_desktop_config.json` with the same content above.

### 4. Restart Claude Desktop

Close and reopen Claude. GitHub tools appear in the sidebar.

---

## 💡 Usage Examples

### Read Code
```
YOU:     "Show me the current trading signal logic"
CLAUDE:  ✓ Fetches src/signals.js
         ✓ Explains the MACD/RSI calculation
         ✓ Points out potential improvements
```

### Update & Commit
```
YOU:     "Update MACD threshold to 0.35 and commit"
CLAUDE:  ✓ Reads current file (gets SHA)
         ✓ Updates the threshold
         ✓ Commits with message: "refactor: adjust MACD threshold to 0.35"
         ✓ Shows commit link
```

### Create Feature Branch
```
YOU:     "Create a branch for fixing the Groww API symbol mapping"
CLAUDE:  ✓ Creates branch: feature/groww-symbol-fix
         ✓ Switches you there
         ✓ Ready to make changes
```

### Batch Commit
```
YOU:     "Add error handling to both index.js and api.js"
CLAUDE:  ✓ Reads both files
         ✓ Adds error handling to both
         ✓ Single commit: "feat: add comprehensive error handling"
```

### Create PR
```
YOU:     "Create a PR for the telegram-alerts branch"
CLAUDE:  ✓ Opens PR with auto-generated title & description
         ✓ Links to Telegram implementation details
         ✓ Shows PR URL
```

---

## 🛠 Tools Available

| Tool | Purpose |
|------|---------|
| **read_file** | Read file contents (get SHA for editing) |
| **write_file** | Create/update file (auto-commits) |
| **delete_file** | Delete file (auto-commits) |
| **list_files** | Browse repo structure |
| **create_branch** | Create new branch from main/other |
| **list_branches** | List all branches |
| **get_branch_info** | Branch details & protection status |
| **commit_multiple** | Batch commit multiple files |
| **create_pull_request** | Open PR (auto-description) |
| **list_commits** | View commit history |
| **get_repo_info** | Repo metadata (stars, language, etc) |
| **search_files** | Find files by pattern/name |

---

## 📋 Multi-Repo Setup

Manage multiple repos in one Claude instance:

```json
{
  "mcpServers": {
    "github-niftybot": {
      "command": "node",
      "args": ["/path/to/github-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx",
        "GITHUB_REPO": "niftybot"
      }
    },
    "github-coexist": {
      "command": "node",
      "args": ["/path/to/github-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx",
        "GITHUB_REPO": "coexist"
      }
    }
  }
}
```

Then in Claude: `"Switch to github-coexist and show me the migrations"`

---

## 🐳 Deployment

### Docker

```bash
docker build -t github-mcp .
docker run -e GITHUB_TOKEN=ghp_xxx \
           -e GITHUB_REPO=niftybot \
           -e GITHUB_OWNER=techybiky \
           github-mcp
```

### Vercel

```bash
vercel --env GITHUB_TOKEN=ghp_xxx --env GITHUB_REPO=niftybot
```

### Railway

```bash
railway link
railway up
```

### Local VPS

```bash
git clone https://github.com/techybiky/github-mcp.git
cd github-mcp
npm install && npm run build
GITHUB_TOKEN=ghp_xxx GITHUB_REPO=niftybot npm start
```

---

## 🌐 HTTP Server (Optional)

If you want to access this from web/mobile (not just Claude):

```bash
npm run http
# Runs on http://localhost:3000
# API Key printed to console
```

**Example API call:**
```bash
curl -X POST http://localhost:3000/api/call \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "read_file",
    "params": {"path": "package.json"}
  }'
```

---

## 🔐 Security

### Token Management

1. **Create token:** https://github.com/settings/tokens/new
2. **Scopes needed:** `repo`, `read:user`, `workflow`
3. **Storage:** Keep in `~/.config/Claude/` (not committed to git)
4. **Rotation:** Regenerate monthly in Settings

### Best Practices

- ✅ Use environment variables (never hardcode)
- ✅ Store config in `~/.config/` (local machine only)
- ✅ Use fine-grained tokens for enterprise
- ✅ Rotate tokens regularly
- ✅ Never commit `claude_desktop_config.json` with real tokens

---

## 🚨 Troubleshooting

### GitHub tools not showing in Claude

**Solution 1: Check config file syntax**
```bash
# macOS/Linux
cat ~/.config/Claude/claude_desktop_config.json | jq .

# Windows - open in text editor and validate JSON
```

**Solution 2: Verify node path**
```bash
which node  # macOS/Linux
where node  # Windows
# Use full path in config: /usr/bin/node or /opt/homebrew/bin/node
```

**Solution 3: Restart Claude Desktop**
- Close completely
- Reopen
- Check sidebar for tools

### "401 Unauthorized"

- Token is invalid/expired → Generate new at https://github.com/settings/tokens
- Token missing scopes → Regenerate with `repo` + `read:user` + `workflow`

### "404 Not Found"

- Wrong repo name → Check `GITHUB_REPO` in config
- Wrong owner → Check `GITHUB_OWNER` in config (default: `techybiky`)
- Token can't access repo → Must have `repo` scope

### "409 Conflict"

- File SHA is stale → Claude auto-retries by re-reading file
- Branch was updated → Try again

---

## 📦 Project Structure

```
github-mcp/
├── src/
│   ├── index.js           # MCP server entry (stdio transport)
│   ├── mcp-server.js      # Tool definitions & handlers
│   ├── github.js          # GitHub REST API wrapper
│   └── http-server.js     # Optional HTTP server
├── dist/                  # Built files (generated)
├── package.json
├── Dockerfile             # For containerized deployment
├── .env.example           # Environment variables template
├── claude_desktop_config.template.json
├── SETUP.md               # Detailed setup instructions
└── README.md              # This file
```

---

## 🎓 How It Works

1. **You talk to Claude** in Claude Desktop
2. **Claude calls tools** from this MCP server (via stdio)
3. **MCP server calls GitHub API** to read/write code
4. **Results come back** as text to Claude
5. **Claude shows you** what was changed + commit links

```
Claude Desktop
    ↓ (stdio)
GitHub MCP Server (this repo)
    ↓ (HTTP)
GitHub REST API
```

---

## 📚 Learning Resources

- **Model Context Protocol:** https://modelcontextprotocol.io
- **GitHub REST API:** https://docs.github.com/en/rest
- **Claude Documentation:** https://docs.claude.com

---

## 💬 Support & Feedback

- Issues: https://github.com/techybiky/github-mcp/issues
- Discussions: https://github.com/techybiky/github-mcp/discussions
- Claude Help: https://support.claude.com

---

## 📄 License

MIT

---

## 🙏 Thanks

Built for KK Das (@techybiky) — SDET, Test Automation Architect, Open Source Builder

**Your repos made easier:** niftybot • coexist • youtube-bot • job-tracker

---

**Ready to get started? → [SETUP.md](SETUP.md)** 🚀