GitHub MCP

A TypeScript-based Model Context Protocol (MCP) server for inspecting public GitHub data through tools that can be consumed by MCP-compatible clients such as Cursor or Claude Desktop.

What this project does

The server currently exposes two tools:

• hello: returns a friendly greeting and serves as a simple protocol sanity check.
• github_user_stats: fetches a GitHub username’s public profile metadata, repository activity totals, recent public events, and pull request insights in one response.

The implementation uses the GitHub REST API to gather public profile information and formats the output into human-readable summaries.

Features

• Lightweight MCP server over stdio transport
• Public GitHub profile and repository stats gathering
• Pull request insights including:
  • total PR count
  • merged PR count
  • co-authored PR count
  • most targeted repository
• Optional authentication via a GitHub token to reduce unauthenticated rate-limit issues
• Test coverage for formatting and helper logic

Getting started

1. Install dependencies

git clone https://github.com/<your-username>/github_mcp.git
cd github_mcp
npm install

2. Configure environment variables

Create a .env file in the project root if you want to use a GitHub token:

GITHUB_TOKEN=your_github_personal_access_token

This is optional, but recommended for smoother API usage.

3. Run the server

npm run dev

The server runs over stdio, so stdout is reserved for MCP protocol traffic and logs are written to stderr.

Example tool calls

Hello

{
  "name": "Mahesh"
}

GitHub stats

{
  "username": "Maheshkumarjena"
}

Scripts

• npm run dev starts the MCP server in development mode
• npm run build compiles the TypeScript project
• npm test runs the Vitest test suite

Project structure

• src/index.ts bootstraps the MCP server
• src/tools.ts registers the available MCP tools
• src/github.ts wraps GitHub API requests and data aggregation
• src/schemas.ts defines tool input validation with Zod
• src/types.ts contains shared TypeScript interfaces
• src/utils.ts formats and transforms data for output
• tests/ contains unit tests for helper behavior

Development notes

The current implementation is intentionally small and focused on a solid foundation for GitHub data access. It is a good starting point for adding more GitHub endpoints and exposing additional MCP tools.

Contributing

1. Fork the repository
2. Create a feature branch
3. Extend the GitHub client in src/github.ts or add new tools in src/tools.ts
4. Run npm test and npm run build before opening a pull request