# GitHub MCP Server

Model Context Protocol server for GitHub repository management and interaction.

## Overview

This MCP server enables AI agents to interact with GitHub repositories via the GitHub REST API. Built with TypeScript using the official MCP SDK and Octokit.

**Version:** 0.3.0 (Phase 3 In Progress)  
**Author:** Pip (@pipseedai)  
**License:** MIT

## Features

### Phase 1: Read Operations ✅

- **`github_list_repos`** - List repositories for a user or organization
- **`github_get_repo`** - Get detailed repository information
- **`github_get_file`** - Read file contents from a repository
- **`github_list_issues`** - List repository issues with filters
- **`github_search_code`** - Search code across GitHub repositories

### Phase 2: Write Operations ✅

- **`github_create_repo`** - Create a new repository
- **`github_create_issue`** - Create an issue with title, body, labels, assignees
- **`github_update_issue`** - Update issue (title, body, state, labels, assignees)
- **`github_create_comment`** - Add comments to issues or pull requests

### Phase 3: Webhook Monitoring 🚧

Real-time GitHub event monitoring with Discord notifications.

**Components:**
- ✅ **Phase 3.1:** HTTP server with SSE transport for MCP tools
- ✅ **Phase 3.2:** Webhook signature verification (HMAC SHA-256)
- ✅ **Phase 3.3:** Discord delivery via webhooks
- 🔲 **Phase 3.4:** Production deployment and GitHub webhook configuration

**Supported Events:**
- Issues (opened, closed, reopened)
- Pull requests (opened, closed, merged)
- Releases (published, created)
- Stars, watches, forks
- Commits, branches, tags

**Event Filtering:** Automatically filters noisy events (individual watch/unwatch, repetitive actions)

### Phase 4: Advanced Features (Future)

- Pull request creation and management
- Branch and commit operations
- Repository forking and starring
- Workflow management

## Installation

```bash
cd ~/.openclaw/workspace/mcp-servers/github
npm install
npm run build
```

## Configuration

### Authentication

Requires a GitHub Personal Access Token stored in `~/.openclaw/secrets/github.env`:

```bash
GITHUB_TOKEN=ghp_your_token_here
```

### Webhook Server (Phase 3)

For real-time GitHub event monitoring, configure webhook secrets and Discord delivery in `~/.openclaw/secrets/github.env`:

```bash
# Required: GitHub webhook secret (set when creating webhook)
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here

# Required: Discord webhook URL for notifications
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Optional: HTTP server port (default: 9999)
PORT=9999
```

**Start the HTTP server:**

```bash
source ~/.openclaw/secrets/github.env
npm run build
node dist/server-http.js
```

**Endpoints:**
- `GET /health` - Server health check
- `GET /sse` - MCP SSE transport (tools still available)
- `POST /webhooks/github` - GitHub webhook receiver

**GitHub Webhook Configuration:**
1. Go to repository Settings → Webhooks → Add webhook
2. Payload URL: `https://your-domain.com/webhooks/github`
3. Content type: `application/json`
4. Secret: Same as `GITHUB_WEBHOOK_SECRET`
5. Events: Choose events to monitor (or "Send me everything")

## Usage

### Via mcporter CLI

**Note:** Make sure `GITHUB_TOKEN` is set in your environment before running these commands.

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

```bash
# List repositories for authenticated user
npx mcporter call --stdio "./path/to/github-mcp/dist/index.js" \
  'github.github_list_repos()'

# Get repository information
npx mcporter call --stdio "./path/to/github-mcp/dist/index.js" \
  'github.github_get_repo(owner: "modelcontextprotocol", repo: "servers")'

# Read file contents
npx mcporter call --stdio "./path/to/github-mcp/dist/index.js" \
  'github.github_get_file(owner: "owner", repo: "repo", path: "README.md")'

# List repository issues
npx mcporter call --stdio "./path/to/github-mcp/dist/index.js" \
  'github.github_list_issues(owner: "owner", repo: "repo", state: "open")'

# Search code
npx mcporter call --stdio "./path/to/github-mcp/dist/index.js" \
  'github.github_search_code(query: "addClass in:file language:js")'
```

## Available Tools

### github_list_repos

List repositories for a user or organization.

**Parameters:**
- `username` (optional) - GitHub username/org (defaults to authenticated user)
- `type` (optional) - Filter: "all", "owner", "member" (default: "owner")
- `sort` (optional) - Sort by: "created", "updated", "pushed", "full_name" (default: "updated")
- `per_page` (optional) - Results per page (default: 30, max: 100)

### github_get_repo

Get detailed information about a repository.

**Parameters:**
- `owner` (required) - Repository owner
- `repo` (required) - Repository name

**Returns:** Repository metadata including description, stars, forks, language, topics, etc.

### github_get_file

Read file contents from a repository.

**Parameters:**
- `owner` (required) - Repository owner
- `repo` (required) - Repository name
- `path` (required) - File path in repository
- `ref` (optional) - Branch, tag, or commit SHA (default: default branch)

**Returns:** Decoded file content as text

### github_list_issues

List issues for a repository.

**Parameters:**
- `owner` (required) - Repository owner
- `repo` (required) - Repository name
- `state` (optional) - "open", "closed", "all" (default: "open")
- `labels` (optional) - Comma-separated label names
- `per_page` (optional) - Results per page (default: 30, max: 100)

### github_search_code

Search for code across GitHub repositories.

**Parameters:**
- `query` (required) - Search query (supports GitHub search syntax)
- `per_page` (optional) - Results per page (default: 30, max: 100)

**Example queries:**
- `"addClass in:file language:js repo:owner/repo"`
- `"function user:pipseedai"`
- `"TODO extension:md"`

### github_create_repo

Create a new GitHub repository.

**Parameters:**
- `name` (required) - Repository name
- `description` (optional) - Repository description
- `private` (optional) - Private repository (default: false)
- `auto_init` (optional) - Initialize with README (default: false)

### github_create_issue

Create a new issue in a repository.

**Parameters:**
- `owner` (required) - Repository owner
- `repo` (required) - Repository name
- `title` (required) - Issue title
- `body` (optional) - Issue description (supports Markdown)
- `labels` (optional) - Array of label names
- `assignees` (optional) - Array of GitHub usernames
- `milestone` (optional) - Milestone number

### github_update_issue

Update an existing issue.

**Parameters:**
- `owner` (required) - Repository owner
- `repo` (required) - Repository name
- `issue_number` (required) - Issue number
- `title` (optional) - New title
- `body` (optional) - New description
- `state` (optional) - "open" or "closed"
- `labels` (optional) - Array of label names (replaces existing)
- `assignees` (optional) - Array of usernames (replaces existing)

### github_create_comment

Add a comment to an issue or pull request.

**Parameters:**
- `owner` (required) - Repository owner
- `repo` (required) - Repository name
- `issue_number` (required) - Issue or PR number
- `body` (required) - Comment text (supports Markdown)

## Rate Limits

- **Authenticated:** 5,000 requests/hour
- **Search:** 30 requests/minute
- Errors (403/429) are caught and returned gracefully

## Development

```bash
# Build
npm run build

# Watch mode
npm run watch
```

## File Structure

```
mcp-servers/github/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   └── index.ts          # Main server implementation
└── dist/                 # Compiled JavaScript
    ├── index.js
    └── index.d.ts
```

## Testing

**Phase 1 (Read Operations):**
- ✅ Authentication with GitHub PAT
- ✅ List repositories
- ✅ Get repository details (tested on modelcontextprotocol/servers)
- ✅ Read file contents (tested on README.md)
- ✅ List issues with filters
- ✅ Search code across repositories

**Phase 2 (Write Operations):**
- ✅ Create repository (tested on pipseedai/mcp-test)
- ✅ Create issues with labels
- ✅ Update issue title, body, state, labels
- ✅ Add comments to issues

**Validation:** All tools tested on https://github.com/pipseedai/mcp-test

## Next Steps

- [ ] Add Phase 3 advanced features (PRs, branches, commits, forks)
- [ ] Add unit tests
- [ ] Improve error handling and validation
- [ ] Add response caching for frequently accessed data
- [ ] Consider GraphQL API for complex queries
- [ ] Add workflow and release management tools

## References

- [GitHub REST API](https://docs.github.com/en/rest)
- [Octokit.js](https://github.com/octokit/octokit.js)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Documentation](https://modelcontextprotocol.io/)

---

**Created:** 2026-02-03  
**Last Updated:** 2026-02-05  
**Repository:** https://github.com/pipseedai/github-mcp