# Building GitHub MCP Agents for Repository Analysis: A Complete Guide

> Build GitHub MCP agents for repository analysis using Agno with MCPTools and a Nebius LLM. Query issues, pull requests, and metadata using natural language in this complete guide.

- Repository: [Arindam Majumder /awesome-ai-apps](https://github.com/Arindam200/awesome-ai-apps)
- Tags: how-to-guide
- Published: 2026-05-06

---

**Building GitHub MCP agents for repository analysis involves wrapping the GitHub MCP server in an Agno Agent with MCPTools, enabling natural language queries against issues, pull requests, and repository metadata through a Nebius LLM backend.**

The `awesome-ai-apps` repository by Arindam200 demonstrates how to build GitHub MCP agents for repository analysis using the Model Context Protocol (MCP). This curated collection contains over 80 AI-powered projects, with the GitHub MCP agent serving as a practical example of integrating external APIs through standardized tool interfaces. By combining the Agno agent framework with Dockerized MCP servers, developers can create natural language interfaces for complex GitHub operations.

## Understanding the MCP Architecture

The GitHub MCP agent in [`mcp_ai_agents/github_mcp_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/mcp_ai_agents/github_mcp_agent/main.py) follows a containerized architecture where an MCP server exposes GitHub API methods via JSON-RPC, consumed by a Python client wrapper. This decoupling allows the LLM to invoke GitHub operations—such as `list_issues` or `list_pull_requests`—as discrete tools without hardcoding API logic into the agent itself.

The architecture consists of five core components working in sequence:

- **Streamlit UI** – Provides a web front-end for API key entry and query submission using `st.text_input` and `st.button` widgets.
- **Nebius LLM** – Powers reasoning through the `Nebius(id="Qwen/Qwen3-30B-A3B")` model instantiation.
- **MCPTools** – Wraps the MCP client session to expose GitHub-specific methods via `MCPTools(session=session)`.
- **MCP Server** – A Docker container running `ghcr.io/github/github-mcp-server` that translates JSON-RPC calls to GitHub REST API requests.
- **Async Runner** – The `run_github_agent` coroutine orchestrates the lifecycle from user input to formatted markdown output.

## How MCP Tools Enable Repository Analysis

The integration follows a strict initialization sequence defined in the source code. First, `StdioServerParameters` configures the Docker container launch parameters, including the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable. The `stdio_client` context manager then establishes a bidirectional pipe to the running container.

Within this session, `MCPTools` registers available GitHub methods:

```python
from agno.tools.mcp import MCPTools
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="docker",
    args=["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"],
    env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.getenv("GITHUB_PERSONAL_ACCESS_TOKEN")}
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        mcp_tools = MCPTools(session=session)
        await mcp_tools.initialize()
        # Tools now available for agent consumption

```

The agent instructions explicitly require concise, markdown-formatted responses with tables and links, ensuring the LLM returns structured repository data rather than conversational text.

## Implementing the GitHub MCP Agent

### Local Setup and Installation

To build GitHub MCP agents for repository analysis locally, clone the repository and install dependencies using `uv`:

```bash
git clone https://github.com/Arindam200/awesome-ai-apps.git
cd awesome-ai-apps
uv pip install -e .

```

Launch the Streamlit interface to interact with the agent:

```bash
streamlit run mcp_ai_agents/github_mcp_agent/main.py

```

The UI exposes sidebar fields for the **Nebius API key** and **GitHub Personal Access Token (PAT)**. These credentials populate environment variables consumed by the `Nebius` model initializer and the MCP server container respectively.

### Programmatic Usage Without UI

For pipeline integration or automated analysis, instantiate the agent directly using the `run_github_agent` pattern:

```python
import asyncio
import os
from agno.agent import Agent
from agno.tools.mcp import MCPTools
from agno.models.nebius import Nebius
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

os.environ["NEBIUS_API_KEY"] = "<YOUR_NEBIUS_API_KEY>"
os.environ["GITHUB_PERSONAL_ACCESS_TOKEN"] = "<YOUR_GITHUB_PAT>"

async def query_repo(repo: str, query: str) -> str:
    server_params = StdioServerParameters(
        command="docker",
        args=["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
              "ghcr.io/github/github-mcp-server"],
        env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.getenv("GITHUB_PERSONAL_ACCESS_TOKEN")}
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            mcp_tools = MCPTools(session=session)
            await mcp_tools.initialize()
            
            agent = Agent(
                tools=[mcp_tools],
                instructions="You are a concise GitHub assistant. Format responses in markdown with tables.",
                model=Nebius(id="Qwen/Qwen3-30B-A3B", 
                           api_key=os.getenv("NEBIUS_API_KEY")),
                markdown=True,
                show_tool_calls=True,
            )
            
            resp = await agent.arun(f"{query} in {repo}")
            return resp.content

# Execute analysis

result = asyncio.run(query_repo(
    repo="Arindam200/awesome-ai-apps",
    query="List recent open issues"
))
print(result)

```

This implementation mirrors the UI flow but enables headless operation for CI/CD pipelines or batch repository auditing.

## Extending the Agent with Custom Tools

The modular architecture supports custom tool registration beyond the default GitHub MCP methods. To add specialized repository analysis—such as identifying top-contributed files or security scan results—extend the `MCPTools` instance before agent initialization:

```python

# After initializing mcp_tools

await mcp_tools.register_tool(
    name="analyze_contribution_patterns",
    description="Analyze contributor commit frequency and file ownership",
    parameters={"repo": "string", "since_days": "integer"},
    rpc_call=lambda repo, days: custom_analysis_logic(repo, days)
)

# The agent automatically invokes this tool when relevant to the query

resp = await agent.arun("Who are the top contributors in Arindam200/awesome-ai-apps over the last 30 days?")

```

Custom tools follow the same JSON-RPC pattern, allowing the Nebius LLM to route requests appropriately based on user intent.

## Key Implementation Files

Understanding the complete system requires reference to these specific files in the `Arindam200/awesome-ai-apps` repository:

- **[`mcp_ai_agents/github_mcp_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/mcp_ai_agents/github_mcp_agent/main.py)** – Contains the full Streamlit UI implementation, `run_github_agent` coroutine, and agent configuration with Nebius LLM integration.
- **[`starter_ai_agents/agno_starter/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/starter_ai_agents/agno_starter/main.py)** – Minimal reference implementation showing the base `Agent` API without MCP complexity.
- **[`mcp_ai_agents/mcp_starter/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/mcp_ai_agents/mcp_starter/main.py)** – Boilerplate template for creating new MCP-backed agents from scratch.
- **[`mcp_ai_agents/doc_mcp/src/github/client.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/mcp_ai_agents/doc_mcp/src/github/client.py)** – Low-level GitHub API client used by specialized MCP implementations.

## Summary

Building GitHub MCP agents for repository analysis combines containerized MCP servers with the Agno agent framework to create powerful natural language interfaces for GitHub data:

- **MCPTools** bridges the gap between the Agno `Agent` and Dockerized MCP servers, exposing GitHub API methods as callable tools.
- The **Nebius LLM** (`Qwen/Qwen3-30B-A3B`) provides reasoning capabilities, configured in [`mcp_ai_agents/github_mcp_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/mcp_ai_agents/github_mcp_agent/main.py) with specific markdown formatting instructions.
- **Authentication** requires both a Nebius API key and GitHub Personal Access Token, passed through environment variables to the respective components.
- **Deployment options** include the Streamlit UI for interactive analysis or programmatic async invocation via `run_github_agent` for automated workflows.
- **Extensibility** comes through the `register_tool` method on `MCPTools`, allowing custom repository analysis logic while maintaining the MCP protocol standards.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) and why use it for GitHub analysis?

The **Model Context Protocol (MCP)** is a standardized interface that allows AI agents to discover and invoke external tools through JSON-RPC. For GitHub repository analysis, MCP decouples the agent logic from API implementation details, allowing the same agent code to work across different GitHub enterprise instances or API versions without modification. The `awesome-ai-apps` repository implements this via `MCPTools(session=session)` to wrap the official GitHub MCP server container.

### How do I authenticate the GitHub MCP agent securely?

Authentication requires two tokens: a **Nebius API key** for the LLM backend and a **GitHub Personal Access Token (PAT)** for API access. In [`mcp_ai_agents/github_mcp_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/mcp_ai_agents/github_mcp_agent/main.py), these are collected through Streamlit sidebar inputs and stored in environment variables (`NEBIUS_API_KEY` and `GITHUB_PERSONAL_ACCESS_TOKEN`). The GitHub token is then passed to the Docker container via `StdioServerParameters` arguments, ensuring the MCP server can authenticate API requests without exposing credentials in code.

### Can I run the GitHub MCP agent without the Streamlit interface?

Yes. While the repository provides a Streamlit UI in [`main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/main.py), the core logic resides in the `run_github_agent` async function, which can be imported and called from any Python script. Remove the Streamlit dependencies and call `asyncio.run(query_repo(...))` directly, passing your credentials via environment variables or function arguments instead of UI inputs.

### Which LLM models work best with GitHub MCP agents?

The reference implementation uses **Nebius** with the `Qwen/Qwen3-30B-A3B` model, chosen for its strong performance on structured data tasks and tool-calling accuracy. However, the Agno framework supports swapping the model provider by changing the `model` parameter in the `Agent` constructor. When substituting models, ensure they support function calling or tool use, as this capability is required for the agent to invoke `MCPTools` methods effectively.