Google ADK MCP to GitHub

A Google Agent Development Kit (ADK) agent that connects to GitHub's hosted Model Context Protocol (MCP) server. This agent provides GitHub authentication and tool integration using OAuth device flow and Google Cloud Secret Manager for secure credential storage. The instructions include the Google ADK CLI command to deploy the agent to Google Cloud Agent Engine.

Features

• GitHub OAuth Authentication: Device flow authentication with GitHub
• Google Cloud Secret Manager Integration: Secure storage of OAuth credentials
• MCP Protocol Support: Dynamic tool loading from GitHub Copilot's MCP server
• Session State Management: Maintains authentication across conversation turns
• Fallback Support: Environment variable fallback for local development

Prerequisites

• Python 3.10+
• Google Cloud Project with billing enabled
• GitHub OAuth App credentials
• Google ADK CLI installed

Installation

1. Clone the repository

   git clone https://github.com/mlaslie/Google-ADK-MCP-to-Github.git
   cd Google-ADK-MCP-to-Github

2. Create and Update .env

   # create the .env in root_agent
   cp env_example.txt root_agent/.env
   
   # update variables as needed
   vim .env
   # or
   nano .env

## Setup
### 1. Create a GitHub OAuth App

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Click "New OAuth App"
3. Fill in the details:
   - **Application name**: Your app name
   - **Homepage URL**: Your app URL
   - **Authorization callback URL**: `https://api.githubcopilot.com/mcp/`
4. Note your **Client ID** and generate a **Client Secret**

### 2. Configure Google Cloud Secret Manager
Run the provided script to set up Secret Manager (update with your values):

```bash
# Edit gcloud_commands.sh and replace:
# - your-gcp-project-id with your actual project ID
# - YOUR_CLIENT_ID with your GitHub OAuth Client ID
# - YOUR_CLIENT_SECRET with your GitHub OAuth Client Secret
# - SERVICE_ACCOUNT_EMAIL with your service account email

chmod +x gcloud_commands.sh
./gcloud_commands.sh

4. Local Testing

Install dependencies

pip install -r root_agent/requirements.txt

Load Environment Variables

source root_agent/.env

Start the Agent

# from parent directory (contains root_agent)
adk web

5. Deploying the Agent to Google Cloud Agent Engine

Google-ADK-MCP-to-Github/
├── .gitignore                 # Git ignore file (Python, env vars, credentials)
└── gcloud_commands.sh         # GCP Secret Manager setup script
  └─→ root_agent
    ├── agent.py                   # Main ADK agent entry point
    ├── auth.py                    # GitHub OAuth + Secret Manager integration
    ├── instructions.py            # System instructions for the agent
    ├── remote_mcp.py              # MCP server connection & dynamic tool loading
    ├── requirements.txt

# from: Google-ADK-MCP-to-Github/
adk deploy agent_engine \
--project=your-gcp-project-id \
--trace_to_cloud \
--description="Google ADK with Github Hosted MCP" \
--requirements_file=requirements.txt \
--display_name="Github MCP v0.1" \
root_agent/

Using the Agent

Authentication Flow

1. Start a conversation with the agent
2. Agent will prompt for GitHub authentication if not logged in
3. Call github_login to get a device code
4. Visit the provided URL and enter the code
5. Reply "Done" or "Ready" when authentication is complete
6. Agent calls github_login_complete to finish authentication

Example Conversation

User: Search for repositories in the google organization
Agent: Let me authenticate you with GitHub first.
      [Calls github_login]
      
      ### 🔐 GitHub Authentication Required
      1. Go to: https://github.com/login/device
      2. Enter this code: XXXX-XXXX
      3. Click 'Authorize'
      
      When you have finished, reply with 'Done'.

User: Done
Agent: [Calls github_login_complete]
      ✅ Authentication Successful! Connected to GitHub.
      
      [Now calls search_repositories]
      Found 50 repositories in the google organization...

Architecture

Components

1. agent.py: Defines the root LLM agent with callbacks
2. auth.py: Handles GitHub OAuth device flow and Secret Manager integration
3. remote_mcp.py: Manages dynamic tool loading from MCP server
4. instructions.py: Provides system instructions for agent behavior

Flow

┌─────────────┐
│   User      │
└──────┬──────┘
       │
       v
┌─────────────────────────────────────┐
│  ADK Agent (agent.py)               │
│  - Model: gemini-2.5-flash          │
│  - Tools: DynamicGitHubMCPToolset   │
└──────┬──────────────────────────────┘
       │
       v
┌─────────────────────────────────────┐
│  DynamicGitHubMCPToolset            │
│  (remote_mcp.py)                    │
│  - Auth Tools (always available)    │
│  - GitHub Tools (when authenticated)│
└──────┬──────────────────────────────┘
       │
       ├─────────────┐
       v             v
┌──────────┐  ┌────────────────────┐
│  Secret  │  │  GitHub MCP Server │
│ Manager  │  │  (Copilot API)     │
└──────────┘  └────────────────────┘

Available Tools

Authentication Tools (Always Available)

• github_login: Start OAuth device flow
• github_login_complete: Complete OAuth authentication
• github_status: Check authentication status

Configuration Options

Environment Variables

Variable	Description	Default
GCP_PROJECT_ID	Google Cloud Project ID	your-gcp-project-id
GITHUB_MCP_URL	MCP server endpoint	https://api.githubcopilot.com/mcp/
MODEL_NAME	Gemini model to use	gemini-2.0-flash
GITHUB_OAUTH_CLIENT_ID	Fallback OAuth Client ID	(from Secret Manager)
GITHUB_OAUTH_CLIENT_SECRET	Fallback OAuth Client Secret	(from Secret Manager)