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

📋 Prerequisites

• Python 3.10+

• A GitHub Personal Access Token (PAT) with required scopes

• uv (recommended) or pip

Required GitHub Token Scopes

💡 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

⚠️ 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:

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:

getRepoActivity

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

Parameters:

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

geAllUserRepo

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

Parameters:

createRepository

Creates a new GitHub repository under the authenticated user.

Parameters:

🔌 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

Built with ❤️ using FastMCP & Python

⭐ Star this repo if you find it helpful!