A Custom GitHub MCP Server that exposes GitHub API operations as AI-ready tools
GitHubMcpServer
A Custom GitHub MCP (Model Context Protocol) Server that exposes GitHub API operations as AI-ready tools for LLM agents and applications.
Overview • Features • Installation • Tools • Configuration • Usage
📖 Overview
GitHubMcpServer is a lightweight, high-performance MCP server built with FastMCP that bridges AI models and the GitHub REST API. It allows AI agents (such as Claude, GPT-4, etc.) to interact with GitHub repositories directly — fetching metadata, managing settings, tracking activity, listing and creating repositories — all through a standardized MCP interface over HTTP.
┌──────────────────────────┐ ┌───────────────────────────┐
│ AI Agent / LLM Client │ ──────▶│ GitHubMcpServer │
│ (Claude, GPT, etc.) │◀────── │ FastMCP • Port 10000 │
└──────────────────────────┘ └──────────────┬────────────┘
│
┌───────────▼────────────┐
│ GitHub REST API v3 │
│ api.github.com │
└────────────────────────┘
✨ Features
| Feature | Description |
|---|---|
| 🔍 Get Repository Info | Fetch detailed metadata for any repository |
| ✏️ Update Repository Settings | Modify name, description, visibility, merge strategies & more |
| 📊 Track Repository Activity | Query push history, branch changes, merges with filtering |
| 📂 List All Repositories | Paginate and sort all user repositories |
| 🆕 Create Repositories | Spin up new repos with custom configuration |
| ⚡ Async & Non-blocking | Built with httpx and async/await for high performance |
| 🌐 CORS Enabled | Ready for browser-based or cross-origin MCP clients |
| 🔒 Secure Auth | Token-based authentication via .env file |
📋 Prerequisites
- Python 3.10+
- A GitHub Personal Access Token (PAT) with required scopes
- `uv` (recommended) or
pip
Required GitHub Token Scopes
| Scope | Purpose |
|---|---|
repo |
Full access to public & private repositories |
read:user |
Read authenticated user profile data |
💡 Generate your token at: GitHub → Settings → Developer Settings → Personal Access Tokens
🚀 Installation
1. Clone the Repository
git clone https://github.com/moksh555/GitHUbMcpServer.git
cd GitHUbMcpServer
2. Install Dependencies
Using uv (recommended):
uv sync
Using pip:
pip install "fastmcp>=3.1.1" httpx pydantic-settings
⚙️ Configuration
Create a .env file in the project root:
GITHUB_ACCESS_TOKEN=ghp_your_personal_access_token_here
OWNER_NAME=your_github_username
| Variable | Required | Description |
|---|---|---|
GITHUB_ACCESS_TOKEN |
✅ | Your GitHub Personal Access Token |
OWNER_NAME |
✅ | Your GitHub username (repository owner) |
⚠️ Never commit your
.envfile to version control. It is already listed in.gitignore.
▶️ Running the Server
uv run python gitHubMcpServer.py
The server starts on http://localhost:10000 using HTTP transport with CORS support.
🛠️ Available MCP Tools
`getUserRepo`
Retrieves detailed information for a specific GitHub repository.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
repoName |
string |
✅ | The name of the repository |
Returns: ID, name, URL, privacy status, description, creation/update timestamps, primary language, open issues count.
`updateRepo`
Updates settings for an existing repository. Only provide fields you want to change.
Parameters:
| Name | Type | Description |
|---|---|---|
repoName |
string |
✅ Current repository name |
name |
string |
New repository name |
description |
string |
New description |
homepage |
string |
Homepage URL |
private |
bool |
true for private, false for public |
visibility |
string |
public or private |
has_issues |
bool |
Enable/disable Issues tab |
has_projects |
bool |
Enable/disable Projects tab |
has_wiki |
bool |
Enable/disable Wiki tab |
default_branch |
string |
Change defa |
Tools (2)
getUserRepoRetrieves detailed information for a specific GitHub repository.updateRepoUpdates settings for an existing repository.Environment Variables
GITHUB_ACCESS_TOKENrequiredYour GitHub Personal Access TokenOWNER_NAMErequiredYour GitHub username (repository owner)Configuration
{ "mcpServers": { "github": { "command": "uv", "args": [ "run", "gitHubMcpServer.py" ], "env": { "GITHUB_ACCESS_TOKEN": "your_token", "OWNER_NAME": "your_username" } } } }