# 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
