GitHub Repository Intelligence MCP Server 🤖

An AI-powered GitHub Repository Intelligence system that allows a Large Language Model (LLM) to explore, inspect, and analyze GitHub repositories through the Model Context Protocol (MCP).

The system combines Qwen, Groq, MCP, and the GitHub REST API to create an agentic workflow where the LLM can understand a user's request, select the appropriate tool, retrieve information from GitHub, and generate a natural-language response.

📋 Table of Contents

• Overview

• Why This Project

• Architecture

• How It Works

• Features

• MCP Tools

• Project Structure

• Components

• Agent Loop

• Example Queries

• Technologies

• Installation

• Configuration

• Running the Project

• Testing

• Example Workflow

• Design Decisions

• Current Limitations

• Future Improvements

• Security

• Learning Outcomes

• Project Status

• Author

Related MCP server: github-repo-mcp-server

🚀 Overview

GitHub Repository Intelligence MCP Server is an agentic AI project that enables an LLM to interact with GitHub repositories through the Model Context Protocol (MCP).

Instead of manually navigating GitHub, searching through files, opening repositories, and inspecting source code, users can interact with their GitHub account using natural language.

For example:

What repositories do I have?

Tell me about my Autonomous-research-agent repository.

Show me the structure of my Autonomous-research-agent repository.

Explain agents/researcher.py.

Where is Tavily used in my Autonomous-research-agent repository?

The AI agent determines which tool is required, calls the MCP server, retrieves the required information from GitHub, and then uses the retrieved information to generate the final response.

💡 Why This Project?

Modern LLM applications are increasingly moving from simple question-answering systems toward agentic systems that can interact with external tools and data sources.

This project demonstrates how an LLM can be connected to an external system using MCP.

Instead of implementing GitHub functionality directly inside the LLM application, the GitHub capabilities are exposed as independent MCP tools.

This creates a clean separation between:

• AI reasoning

• Tool orchestration

• MCP communication

• GitHub API integration

The result is a modular architecture that can be extended with additional tools in the future.

🧠 Architecture

The overall architecture is:

                         ┌──────────────────────┐
                         │        User          │
                         │ Natural Language     │
                         │       Query          │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │     Qwen / Groq      │
                         │                      │
                         │   LLM Reasoning      │
                         │   Tool Selection     │
                         └──────────┬───────────┘
                                    │
                                    │ Tool Call
                                    ▼
                         ┌──────────────────────┐
                         │      MCP Client      │
                         │       agent.py       │
                         └──────────┬───────────┘
                                    │
                                    │ MCP Protocol
                                    ▼
                         ┌──────────────────────┐
                         │      MCP Server      │
                         │       server.py      │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │     Tool Layer       │
                         │ repositories.py      │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │    GitHub Client     │
                         │  github_client.py    │
                         └──────────┬───────────┘
                                    │
                                    │ GitHub REST API
                                    ▼
                         ┌──────────────────────┐
                         │       GitHub         │
                         │    Repositories      │
                         │    Files / Code      │
                         └──────────────────────┘

The result is then returned through the same chain:

GitHub
   ↓
GitHub Client
   ↓
Tool Layer
   ↓
MCP Server
   ↓
MCP Client
   ↓
Qwen / Groq
   ↓
Natural Language Answer

🔄 How It Works

The system follows an agentic tool-calling workflow.

Step 1 — User Query

The user provides a natural-language request.

Example:

Where is Tavily used in my Autonomous-research-agent repository?

Step 2 — Tool Discovery

The MCP client connects to the MCP server and discovers the available tools.

The current MCP server exposes:

get_my_repositories
get_repository
list_files
read_file
search_code

Step 3 — LLM Reasoning

The available tools are converted into a format that can be used by the Groq API.

Qwen receives:

• The system instructions

• The user's question

• The available tools

The model determines which tool is appropriate.

For the Tavily example, it can select:

search_code

Step 4 — MCP Tool Execution

The MCP client sends the tool request to the MCP server.

The MCP server executes the corresponding Python function.

Step 5 — GitHub API Request

The tool layer calls the GitHubClient.

The GitHub client communicates with the GitHub REST API using the authenticated GitHub token.

Step 6 — Tool Result

The GitHub data is returned to the MCP server and then to the MCP client.

Step 7 — LLM Receives the Result

The tool result is added to the conversation as a tool message.

Qwen receives the retrieved information and decides whether:

• More tools are required

• Or enough information exists to answer the user

Step 8 — Final Answer

Once enough information has been collected, Qwen generates the final natural-language response.

✨ Features

🔍 Repository Discovery

Retrieve repositories belonging to the authenticated GitHub account.

The system can return information such as:

• Repository name

• Full repository name

• Visibility

• Description

• GitHub URL

📊 Repository Information

Retrieve detailed information about a specific repository.

The returned information includes:

• Repository name

• Full name

• Description

• Visibility

• Primary programming language

• Stars

• Forks

• Open issues

• Default branch

• Creation date

• Last update date

• GitHub URL

📁 Repository File Exploration

The list_files tool allows the agent to explore repository files and directories.

The tool supports directory paths, allowing the agent to progressively explore a repository.

For example:

list_files(
    repo="Autonomous-research-agent",
    path=""
)

Then:

list_files(
    repo="Autonomous-research-agent",
    path="agents"
)

Then:

list_files(
    repo="Autonomous-research-agent",
    path="tools"
)

This allows the agent to construct a repository tree.

📖 File Reading

The read_file tool retrieves the content of a specific repository file.

For example:

read_file(
    repo="Autonomous-research-agent",
    path="agents/researcher.py"
)

The retrieved content can then be analyzed by the LLM.

This allows users to ask questions such as:

Explain agents/researcher.py.

or:

What does this file do?

🔎 Code Search

The search_code tool searches for a text string across repository files.

It can be used to find:

• Functions

• Classes

• Variables

• Libraries

• APIs

• Configuration values

• Imports

• Any specific text

For example:

search_code(
    repo="Autonomous-research-agent",
    query="Tavily"
)

The result includes:

• File path

• Matching line number

• Matching line content

• GitHub URL

🤖 Agentic Tool Selection

The LLM automatically determines which tool should be used.

The application does not require the user to manually select a tool.

For example:

User:
"What repositories do I have?"

The LLM can select:

get_my_repositories

For:

"Tell me about my Autonomous-research-agent repository."

The LLM can select:

get_repository

For:

"Explain agents/researcher.py."

The LLM can select:

read_file

For:

"Where is Tavily used?"

The LLM can select:

search_code

🔁 Multi-Step Reasoning

The agent can execute multiple tool calls when a request requires additional information.

For example, a repository structure request can result in:

list_files("")
       ↓
list_files("agents")
       ↓
list_files("config")
       ↓
list_files("models")
       ↓
list_files("reports")
       ↓
list_files("tests")
       ↓
list_files("tools")
       ↓
Final Answer

This creates a practical agentic workflow instead of a single API call.

🛠️ MCP Tools

The MCP server currently provides five tools.

📂 Project Structure

GitHub-MCP-server/
│
├── src/
│   │
│   ├── __init__.py
│   │
│   ├── agent.py
│   │
│   ├── server.py
│   │
│   ├── github_client.py
│   │
│   ├── test_client.py
│   │
│   └── tools/
│       │
│       ├── __init__.py
│       │
│       └── repositories.py
│
├── .env
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

🧩 Components

src/agent.py

This is the main AI agent.

It is responsible for:

• Starting the MCP server

• Creating the MCP client

• Connecting to the MCP server using stdio

• Discovering available MCP tools

• Converting MCP tools into Groq-compatible function tools

• Sending user queries to Qwen

• Processing LLM tool calls

• Calling MCP tools

• Sending tool results back to Qwen

• Managing the agent loop

• Returning the final natural-language response

The agent supports multiple tool-calling steps.

A maximum number of steps is defined to prevent an infinite loop.

MAX_STEPS = 8

src/server.py

This file implements the MCP server.

It creates the MCP server using the MCP Python SDK:

from mcp.server.mcpserver import MCPServer

The server exposes the GitHub functionality as MCP tools.

The tools currently exposed are:

get_my_repositories
get_repository
list_files
read_file
search_code

The server communicates with the MCP client through standard input/output.

src/github_client.py

This module handles communication with the GitHub REST API.

The GitHubClient class is responsible for:

• GitHub authentication

• Getting the authenticated user

• Getting repositories

• Getting repository details

• Listing repository files

• Reading repository files

• Searching repository code

The client uses httpx.AsyncClient for asynchronous HTTP requests.

src/tools/repositories.py

This module acts as an abstraction layer between the MCP server and the GitHub client.

It calls the appropriate methods from GitHubClient and converts the raw GitHub API responses into structured results.

This separation keeps the architecture modular.

src/test_client.py

This is a lightweight MCP client used for testing the MCP server independently from the AI agent.

It verifies:

• MCP server startup

• MCP client connection

• Tool discovery

• Tool execution

This makes it useful during development and debugging.

🔁 Agent Loop

The core agent follows a repeated loop.

Conceptually:

User Query
    ↓
Qwen
    ↓
Does Qwen need a tool?
    │
    ├── No ──→ Final Answer
    │
    └── Yes
          ↓
      Tool Call
          ↓
      MCP Client
          ↓
      MCP Server
          ↓
      GitHub API
          ↓
      Tool Result
          ↓
        Qwen
          │
          ├── Need more information
          │         ↓
          │      Another Tool Call
          │
          └── Enough information
                    ↓
               Final Answer

The implementation limits the number of iterations using:

MAX_STEPS = 8

This prevents the agent from continuing indefinitely.

💬 Example Queries

1. List Repositories

User:

What repositories do I have?

Expected tool:

get_my_repositories

2. Repository Information

User:

Tell me about my Autonomous-research-agent repository.

Expected tool:

get_repository

3. Repository Structure

User:

Show me the structure of my Autonomous-research-agent repository.

The agent can use:

list_files

multiple times to explore directories.

Example workflow:

list_files("")
        ↓
list_files("agents")
        ↓
list_files("config")
        ↓
list_files("models")
        ↓
list_files("reports")
        ↓
list_files("tests")
        ↓
list_files("tools")
        ↓
Final repository tree

4. File Explanation

User:

Explain agents/researcher.py in my Autonomous-research-agent repository.

The agent uses:

read_file

The file content is then provided to Qwen for analysis.

5. Code Search

User:

Where is Tavily used in my Autonomous-research-agent repository?

The agent uses:

search_code

The tool searches the repository and returns matching files and lines.

The LLM can then summarize the results.

🧪 Example Result

A query such as:

Where is Tavily used in my Autonomous-research-agent repository?

can result in findings such as:

tools/web_search.py
config/settings.py
requirements.txt
agents/researcher.py
agents/report_generator.py
utils/retry.py
.env.example
README.md

The LLM can then explain how Tavily is integrated and where it is consumed in the project.

🧰 Technologies

Python

The main programming language used to implement the application.

Model Context Protocol

MCP is used as the communication protocol between the AI application and the available tools.

Qwen

Qwen is used as the reasoning model responsible for understanding user requests and selecting tools.

Groq

Groq provides the API interface used to run the Qwen model.

GitHub REST API

GitHub's API provides repository information, files, and source-code data.

HTTPX

Used for asynchronous HTTP requests to the GitHub API.

python-dotenv

Used to load environment variables from the .env file.

asyncio

Used to run the asynchronous MCP and GitHub operations.

📦 Installation

Prerequisites

Make sure you have:

• Python 3.10+

• A GitHub account

• A GitHub Personal Access Token

• A Groq API key

1. Clone the Repository

git clone https://github.com/Ibrahimhussein711/GitHub-MCP-server.git

Move into the project directory:

cd GitHub-MCP-server

2. Create a Virtual Environment

On Windows:

python -m venv .venv

Activate the environment:

.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

🔐 Configuration

Create a .env file in the project root:

GITHUB_TOKEN=your_github_token
GROQ_API_KEY=your_groq_api_key

GitHub Token

The GitHub token is used to authenticate requests to the GitHub REST API.

Groq API Key

The Groq API key is used to access the Qwen model through Groq.

⚠️ Environment Variable Security

Never commit your .env file to GitHub.

The repository includes a .gitignore file that excludes:

.venv/
.env
__pycache__/
*.pyc

A safe .env.example file is included:

GITHUB_TOKEN=
GROQ_API_KEY=

Users can copy this file and add their own credentials.

▶️ Running the Project

Make sure your virtual environment is activated.

From the project root, run:

python -m src.agent

The application will display:

Ask me something about your GitHub:

You can then enter a natural-language request.

For example:

What repositories do I have?

or:

Show me the structure of my Autonomous-research-agent repository.

or:

Where is Tavily used in my Autonomous-research-agent repository?

🧪 Testing

The project includes a lightweight MCP test client.

Run:

python -m src.test_client

This test verifies that the MCP communication works correctly without involving the LLM.

The test confirms:

MCP Client
    ↓
MCP Server
    ↓
MCP Tool
    ↓
GitHub API
    ↓
Result

🔬 MCP Communication

The application uses the MCP Python SDK.

The MCP server is started as a subprocess using:

StdioServerParameters(
    command=sys.executable,
    args=["-m", "src.server"],
)

The client then connects to the server:

async with Client(server) as mcp_client:

The client discovers the available tools:

tools_result = await mcp_client.list_tools()

The discovered tools are then converted into the format expected by Groq.

🔗 Tool Calling

The LLM receives the available tools as function definitions.

Each tool contains:

• Name

• Description

• Input schema

For example:

get_repository

can be represented to the LLM with a schema containing:

repo: string

When the LLM decides to use a tool, it generates a tool call.

The agent extracts:

tool name
tool arguments
tool call ID

The MCP client then executes the corresponding MCP tool.

🧱 Layered Architecture

The project follows a layered architecture:

┌───────────────────────────────┐
│       AI Agent Layer          │
│          agent.py             │
└───────────────┬───────────────┘
                │
┌───────────────▼───────────────┐
│          MCP Layer            │
│          server.py            │
└───────────────┬───────────────┘
                │
┌───────────────▼───────────────┐
│         Tool Layer            │
│     tools/repositories.py     │
└───────────────┬───────────────┘
                │
┌───────────────▼───────────────┐
│       GitHub API Layer        │
│       github_client.py        │
└───────────────┬───────────────┘
                │
┌───────────────▼───────────────┐
│          GitHub API            │
└───────────────────────────────┘

This separation provides better maintainability and makes future extensions easier.

⚡ Design Decisions

Why MCP?

MCP provides a standardized interface for connecting AI applications with external tools and data sources.

Instead of tightly coupling the AI agent with GitHub-specific logic, GitHub operations are exposed through MCP tools.

This makes the system easier to extend.

Why Separate the GitHub Client?

The GitHub API implementation is isolated inside:

github_client.py

This prevents GitHub-specific HTTP logic from being mixed with MCP logic.

The MCP server only needs to expose tools.

The GitHub client handles API communication.

Why Have a Tool Layer?

The file:

tools/repositories.py

acts as an abstraction between the MCP server and the GitHub client.

This makes it possible to change the GitHub implementation without heavily modifying the MCP server.

Why Use an Agent Loop?

A single tool call is not enough for complex repository questions.

For example:

Show me the repository structure.

may require several calls:

list_files("")
list_files("agents")
list_files("config")
list_files("models")
list_files("tools")
...

The agent loop allows the LLM to continue calling tools until it has enough information to answer.

🚧 Current Limitations

The current implementation is an MVP focused on GitHub repository exploration and code intelligence.

Some limitations include:

Large Repository Performance

The current search_code implementation retrieves the repository tree and reads files individually.

For very large repositories, this can result in many GitHub API requests.

GitHub Pagination

The current implementation is primarily designed for the current MVP workflow and does not provide a complete pagination abstraction for every GitHub endpoint.

Search Optimization

The current search implementation performs text matching across repository files.

It does not yet provide semantic code search or advanced ranking.

Repository Scope

The current tools focus mainly on:

• Repositories

• Files

• File content

• Code search

Other GitHub resources are not currently exposed as MCP tools.

🔮 Future Improvements

Potential future improvements include:

🌳 Repository Tree Tool

Add a dedicated:

get_repository_tree

tool to retrieve repository structure more efficiently.

🔎 Improved Code Search

Improve code search performance by:

• Reducing GitHub API calls

• Adding search ranking

• Supporting GitHub's native code search

• Adding semantic search

🧠 Semantic Code Intelligence

Add embeddings and vector search to allow queries such as:

Where is authentication implemented?

even when the exact word "authentication" is not present.

🏗️ Architecture Analysis

Add tools that allow the agent to understand:

What are the main components of this project?

Explain the architecture of this repository.

📦 Dependency Analysis

Analyze:

requirements.txt
package.json
pyproject.toml

and explain project dependencies.

📜 Commit Analysis

Add tools for:

• Commit history

• Recent changes

• Contributors

• Changed files

🔀 Pull Request Intelligence

Allow users to ask:

What changed in the latest pull request?

Summarize this pull request.

🐛 Issue Intelligence

Add GitHub issue tools to support questions such as:

What are the open issues in this repository?

💾 Caching

Add caching to reduce repeated GitHub API requests and improve performance.

🔒 Security

The project uses environment variables for sensitive credentials.

Credentials should never be hard-coded into source files.

Sensitive files are excluded through .gitignore:

.env

The GitHub token is only used for authenticated requests to the GitHub API.

Before publishing the project, always verify that no secrets have been committed.

You can check staged files using:

git status

🎯 Learning Outcomes

This project demonstrates practical experience with:

• Generative AI

• Agentic AI

• LLM tool calling

• Function calling

• Model Context Protocol

• MCP Client / Server architecture

• API integration

• GitHub REST API

• Asynchronous Python

• Tool discovery

• Multi-step agent loops

• Structured tool schemas

• Environment variable management

• Modular software architecture

📈 What Makes This Project Different?

This is not simply a chatbot connected to GitHub.

The main goal is to demonstrate an agentic architecture.

The LLM is given access to multiple tools and is responsible for determining:

What information do I need?
        ↓
Which tool can provide it?
        ↓
What parameters should I provide?
        ↓
Do I need another tool?
        ↓
Do I have enough information?
        ↓
Generate the final answer.

This makes the project a practical example of how LLMs can interact with external systems through a standardized tool protocol.

🧪 Verified Workflows

The current implementation has been tested with several workflows.

Repository Discovery

User Query
    ↓
Qwen
    ↓
get_my_repositories
    ↓
GitHub API
    ↓
Repository List
    ↓
Qwen
    ↓
Final Answer

Repository Information

User Query
    ↓
Qwen
    ↓
get_repository
    ↓
GitHub API
    ↓
Repository Details
    ↓
Qwen
    ↓
Final Answer

Repository Structure

User Query
    ↓
Qwen
    ↓
list_files
    ↓
More list_files calls
    ↓
Repository Structure
    ↓
Qwen
    ↓
Clean Tree

File Analysis

User Query
    ↓
Qwen
    ↓
read_file
    ↓
GitHub API
    ↓
File Content
    ↓
Qwen
    ↓
File Explanation

Code Search

User Query
    ↓
Qwen
    ↓
search_code
    ↓
Repository Files
    ↓
Matching Lines
    ↓
Qwen
    ↓
Code Search Summary

📌 Project Status

MVP Completed and Functional ✅

The current version successfully demonstrates an end-to-end agentic workflow:

User
  ↓
Qwen / Groq
  ↓
MCP Client
  ↓
MCP Server
  ↓
GitHub API
  ↓
MCP Client
  ↓
Qwen / Groq
  ↓
Natural Language Answer

The project currently supports:

• Repository discovery

• Repository information

• File exploration

• File reading

• Code searching

• Automatic tool selection

• Multi-step tool execution

• Natural-language repository analysis

👨‍💻 Author

Ibrahim Hussein

Senior Electronics & Electrical Communication Engineering Student

Interests

• Generative AI

• Agentic AI

• Machine Learning

• RAG Systems

• AI Automation

• Software Engineering

• Intelligent Systems

⭐ Support

If you find this project useful or interesting, consider giving the repository a ⭐ on GitHub.

Repository:

https://github.com/Ibrahimhussein711/GitHub-MCP-server

📄 License

This project is intended for educational, experimental, and portfolio purposes.