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.2.0 (Phase 2 Complete)
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: Advanced Features (Future)

• Pull request creation and management

• Branch and commit operations

• Repository forking and starring

• Workflow and release management

Installation

Authentication

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

Usage

Via mcporter CLI

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

File Structure

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