GitHub MCP Client with Gemini LLM

A Model Context Protocol (MCP) client that connects to GitHub's MCP server and uses Google's Gemini LLM for intelligent interactions.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows LLM applications to access data, prompts, and tools in a standardized way. Think of it as a universal adapter between AI models and external services.

Key Concepts:

• MCP Server: Exposes tools, resources, and prompts (e.g., GitHub's MCP server provides tools like search_repositories, create_issue)
• MCP Client: Connects to servers and makes their tools available to applications
• Transport: The communication layer (this project uses stdio transport)

My Learning Journey

The Challenge

Build a simple MCP client and connect it with a free LLM to interact with GitHub.

What I Learned

1. MCP Architecture: Understanding how clients and servers communicate via transports
2. Tool Calling: How LLMs use function declarations to decide when to call external tools
3. Schema Sanitization: Gemini's API is strict about JSON Schema format—learned to strip unsupported fields
4. Rate Limiting: Handling 429 errors with exponential backoff retry logic
5. ESM in Node.js: Using tsx for proper ESM TypeScript module resolution

Project Structure

src/
├── index.ts          # Entry point - orchestrates the client
├── config.ts         # Zod-validated environment config
├── mcp-client.ts     # MCPClient class for server communication
└── gemini-adapter.ts # Gemini LLM integration with retry logic

Prerequisites

• Node.js 18+
• GitHub Personal Access Token
• Google Gemini API Key

Setup

1. Clone and install dependencies:

   git clone <repo-url>
   cd github-mcp
   npm install

2. Create .env file:

   GITHUB_TOKEN=your_github_personal_access_token
   GEMINI_API_KEY=your_gemini_api_key

3. Get your tokens:

   • GitHub: Settings → Developer settings → Personal access tokens
   • Gemini: Google AI Studio

How to Run

Default prompt:

npm run dev

Custom prompt:

npm run dev "List all my repositories with more than 10 stars"

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   User      │────▶│   Gemini    │────▶│  MCP Client
│   Prompt    │     │   (LLM)     │     │             │
└─────────────┘     └──────┬──────┘     └──────┬──────┘
                          │                    │
                          │  Tool Calls        │ Stdio Transport
                          ▼                    ▼
                    ┌─────────────┐     ┌─────────────┐
                    │ Tool Results│◀────│ GitHub MCP  │
                    │             │     │   Server    │
                    └─────────────┘     └─────────────┘

1. User provides a natural language prompt
2. Gemini receives the prompt along with available GitHub tools
3. Gemini decides which tools to call and with what arguments
4. MCP Client executes the tools via the GitHub MCP server
5. Results are sent back to Gemini for final response

Tech Stack

• TypeScript - Type-safe JavaScript
• Zod - Runtime schema validation
• @modelcontextprotocol/sdk - Official MCP client SDK
• @google/generative-ai - Gemini API SDK
• tsx - Modern TypeScript runner for ESM