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

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:

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:

# 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:

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.

export GITHUB_TOKEN=ghp_your_token_here

# 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

# 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
• Octokit.js
• MCP TypeScript SDK
• MCP Documentation

---

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