MCP GitHub Agent - Your Personal GitHub Explorer!

Create a GitHub agent that uses MCP to explore, analyze, and provide insights about GitHub repositories.

Create a GitHub agent that uses MCP to explore, analyze, and provide insights about GitHub repositories. The agent leverages the Model Context Protocol (MCP) to interact with GitHub, allowing it to answer questions about issues, pull requests, repository details and more.

The source excerpt uses the archived npm GitHub server and does not forward its token. Apply the maintained-server configuration in the setup steps before running.

github.py
"""MCP GitHub Agent - Your Personal GitHub Explorer!

This example shows how to create a GitHub agent that uses MCP to explore,
analyze, and provide insights about GitHub repositories. The agent leverages the Model
Context Protocol (MCP) to interact with GitHub, allowing it to answer questions
about issues, pull requests, repository details and more.

Example prompts to try:
- "List open issues in the repository"
- "Show me recent pull requests"
- "What are the repository statistics?"
- "Find issues labeled as bugs"
- "Show me contributor activity"

Run: `uv pip install agno mcp openai` to install the dependencies
Environment variables needed:
- Create a GitHub personal access token following these steps:
    - https://github.com/modelcontextprotocol/servers/tree/main/src/github#setup
- export GITHUB_TOKEN: Your GitHub personal access token
"""

import asyncio
from textwrap import dedent

from agno.agent import Agent
from agno.tools.mcp import MCPTools
from mcp import StdioServerParameters

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------


async def run_agent(message: str) -> None:
    """Run the GitHub agent with the given message."""

    # Initialize the MCP server
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-github"],
    )

    # Create a client session to connect to the MCP server
    async with MCPTools(server_params=server_params) as mcp_tools:
        agent = Agent(
            tools=[mcp_tools],
            instructions=dedent("""\
                You are a GitHub assistant. Help users explore repositories and their activity.

                - Use headings to organize your responses
                - Be concise and focus on relevant information\
            """),
            markdown=True,
        )

        # Run the agent
        await agent.aprint_response(message, stream=True)


# Example usage
# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    # Pull request example
    asyncio.run(
        run_agent(
            "Tell me about Agno. Github repo: https://github.com/agno-agi/agno. You can read the README for more information."
        )
    )


# More example prompts to explore:
"""
Issue queries:
1. "Find issues needing attention"
2. "Show me issues by label"
3. "What issues are being actively discussed?"
4. "Find related issues"
5. "Analyze issue resolution patterns"

Pull request queries:
1. "What PRs need review?"
2. "Show me recent merged PRs"
3. "Find PRs with conflicts"
4. "What features are being developed?"
5. "Analyze PR review patterns"

Repository queries:
1. "Show repository health metrics"
2. "What are the contribution guidelines?"
3. "Find documentation gaps"
4. "Analyze code quality trends"
5. "Show repository activity patterns"
"""

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U "agno[mcp]" openai

Prepare Docker

Install and start Docker for the maintained GitHub MCP server used below. Verify it is available with docker --version.

Export environment variables

export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_personal_access_token_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Use GitHub's maintained MCP server

Install and start Docker. Use a GitHub personal access token with access to the repositories you want to read. The archived npm server is replaced by GitHub's maintained MCP server.

Add these imports to the saved file:

from os import environ
from mcp import StdioServerParameters

Inside run_agent, replace the old server configuration with:

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

Use async with MCPTools(server_params=server_params) as mcp_tools: around the existing Agent and response code. The explicit env mapping forwards the token into the child process; exporting it in the parent shell alone does not do that.

Run the example

Save the code above as github.py, then run:

python github.py

Full source: cookbook/91_tools/mcp/github.py