GitHubMcpServer

<div align="center">

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

</div>

---

📖 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 .env file 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 default branch name
allow_squash_merge	bool	Allow squash merging
archived	bool	Archive the repository

---

getRepoActivity

Fetches a list of recent activities (pushes, merges, branch changes) for a repository.

Parameters:

Name	Type	Description
repoName	string	✅ Repository name
direction	string	asc or desc
ref	string	Git reference (e.g. refs/heads/main)
actor	string	Filter by username
timePeriod	string	day, week, or month
activityType	string	push, force_push, branch_creation, etc.

Returns: Activity ID, user, type, branch, before/after SHA, timestamp.

---

geAllUserRepo

Lists all repositories for the authenticated user with pagination and sorting.

Parameters:

Name	Type	Description
per_page	int	Results per page (default: 30)
page	int	Page number for pagination
sort	string	Sort by: created, updated, pushed, full_name

---

createRepository

Creates a new GitHub repository under the authenticated user.

Parameters:

Name	Type	Description
name	string	✅ Repository name
description	string	Short description
private	bool	true for private (default: false)
auto_init	bool	Initialize with a README

---

🔌 Connecting an AI Client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:10000/mcp",
      "transport": "http"
    }
  }
}

Python MCP Client

from mcp import ClientSession
from mcp.client.http import http_client

async with http_client("http://localhost:10000/mcp") as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("getUserRepo", {"repoName": "my-repo"})
        print(result)

---

📁 Project Structure

GitHUbMcpServer/
├── gitHubMcpServer.py   # Main MCP server & all tool definitions
├── config.py            # Pydantic settings & .env loader
├── pyproject.toml       # Project metadata & dependencies
├── .python-version      # Python version pin
├── .gitignore           # Git ignore rules
├── uv.lock              # Locked dependency versions
└── README.md            # Project documentation

---

🤝 Contributing

Contributions, issues and feature requests are welcome!

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m "Add amazing feature"
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

---

👤 Author

moksh555 · GitHub Profile

---

<div align="center">

Built with ❤️ using <a href="https://github.com/jlowin/fastmcp">FastMCP</a> & Python

⭐ Star this repo if you find it helpful!

</div>