Building GitHub MCP Agents for Repository Analysis: A Complete Guide

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

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:

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:

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:

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:

# 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 – Contains the full Streamlit UI implementation, run_github_agent coroutine, and agent configuration with Nebius LLM integration.
• 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 – Boilerplate template for creating new MCP-backed agents from scratch.
• 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 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}