GitHub MCP TypeScript SDK Server

A comprehensive Model Context Protocol (MCP) server for GitHub that provides access to repositories, issues, pull requests, commits, and user information through a standardized interface. Built with TypeScript and the official MCP SDK.

🚀 Features

📋 Available Tools (10 Total)

• get_my_info - Get information about the authenticated GitHub user

• get_repo_info - Get detailed information about a GitHub repository

• list_repo_issues - List issues in a repository (with state filtering)

• list_repo_prs - List pull requests in a repository

• list_repo_commits - List recent commits in a repository

• search_repositories - Search for repositories on GitHub

• get_user_info - Get information about any GitHub user

• list_user_repos - List repositories belonging to a user

• get_my_repos - List repositories belonging to the authenticated user

• get_github_stats - Get comprehensive GitHub statistics for a user

🔧 Capabilities

• ✅ Repository Information - Name, description, stars, forks, language, visibility

• ✅ Issue Management - List, filter, and view issue details

• ✅ Pull Request Tracking - View PR status, authors, and details

• ✅ Commit History - Browse recent commits with author and message info

• ✅ User Profiles - Access user information and statistics

• ✅ Repository Search - Advanced search with filters and sorting

• ✅ Statistics & Analytics - Comprehensive user and repository metrics

• ✅ Error Handling - Robust error handling with descriptive messages

• ✅ Natural Language Queries - Ask questions in plain English

📦 Installation

Prerequisites

• Node.js 18+

• npm or yarn

• GitHub Personal Access Token

Setup

1. Clone the repository:

   git clone <your-repo-url> cd github-mcp-ts-sdk

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp env.example .env # Edit .env and add your GitHub token

4. Build the project:

   npm run build

🔑 GitHub Token Setup

1. Go to GitHub Settings > Personal Access Tokens

2. Click "Generate new token (classic)"

3. Select the following scopes:

   • repo (Full control of private repositories)

   • user (Read all user profile data)

   • read:org (Read org and team membership)

4. Copy the generated token and add it to your .env file:

🚀 Usage

Development Mode

Production Mode

Watch Mode (for development)

Test the Server

🛠 Tool Examples

User Information

Get Your GitHub Profile

Response:

Get User Information

Repository Information

Get Repository Details

Response:

Search Repositories

Advanced search examples:

• language:javascript - Search by programming language

• stars:>5000 - Filter by minimum stars

• user:octocat - Search within a specific user's repositories

• language:python stars:>1000 forks:>100 - Combined filters

• created:>2023-01-01 - Filter by creation date

• topic:react - Search by topic tags

Issues and Pull Requests

List Repository Issues

List Pull Requests

Commit History

List Recent Commits

Statistics

Get User Statistics

Response:

📚 Resources

Repository Resource

Access repository data via URI: github://repository/{owner}/{repo}

Examples:

• github://repository/microsoft/vscode

• github://repository/facebook/react

User Resource

Access user data via URI: github://user/{username}

Examples:

• github://user/octocat

• github://user/Om-Shree-0709

💬 Prompts

Natural Language Queries

Ask questions in natural language about GitHub data:

Supported queries:

• "Show me my most starred repositories"

• "Search for TypeScript repositories"

• "What are the open issues in microsoft/vscode?"

• "List my repositories"

• "Get statistics for user octocat"

🔧 Configuration

Environment Variables

Create a .env file with:

GitHub Token Scopes

Your GitHub token needs these scopes:

• repo - Full control of private repositories

• user - Read all user profile data

• read:org - Read org and team membership

🏗 Architecture

The server is built using:

• TypeScript - Type-safe development

• MCP SDK - Model Context Protocol framework

• Octokit - Official GitHub API client

• Zod - Schema validation

• Stdio Transport - Standard input/output communication

Project Structure

🔗 Integration

With Claude Desktop

Add to your Claude Desktop configuration:

With Other MCP Clients

The server communicates via stdio and follows the MCP protocol specification. It works with any MCP-compatible client that can send JSON-RPC requests.

Direct JSON-RPC Usage

Send JSON-RPC 2.0 requests to your server:

🛡 Error Handling

The server includes comprehensive error handling:

• ✅ Authentication errors - Clear messages for invalid tokens

• ✅ Rate limiting - Handles GitHub API rate limits gracefully

• ✅ Network errors - Robust handling of connection issues

• ✅ Validation errors - Input validation with helpful error messages

• ✅ GitHub API errors - Detailed error reporting from GitHub

📈 Performance Features

• Efficient API usage - Optimized requests with proper pagination

• Caching-friendly - Responses designed for easy caching

• Rate limit aware - Respects GitHub API rate limits

• Batch operations - Efficient handling of multiple requests

🎯 Practical Use Cases

1. Repository Research

2. User Analysis

3. Project Discovery

4. Your Own Data

📝 Development

Available Scripts

• npm run build - Build the TypeScript project

• npm run build:watch - Build with file watching

• npm run dev - Run in development mode

• npm start - Run the compiled server

• npm test - Test the server

• npm run setup - Run setup script

• npm run demo - Run demo script

• npm run interactive-test - Run interactive tests

Adding New Tools

1. Create a new function in src/server.ts

2. Register the tool with server.registerTool()

3. Add proper error handling

4. Update this README

Testing

🚨 Troubleshooting

Common Issues

1. "Cannot find module" errors

   • Run npm install to install dependencies

   • Run npm run build to compile TypeScript

2. Authentication failures

   • Check your GitHub token is valid

   • Ensure token has required scopes

   • Verify .env file exists and is readable

3. Rate limit errors

   • Wait before making more requests

   • Consider using a token with higher rate limits

4. Repository not found

   • Check owner and repository names are correct

   • Ensure repository is public or you have access

Debug Mode

Run in development mode for detailed logging:

📊 Response Format

All tools return responses in the MCP standard format with content arrays containing text blocks:

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Add your changes

4. Test thoroughly

5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

• Issues: Report bugs and feature requests via GitHub Issues

• Documentation: Check the MCP specification for protocol details

• GitHub API: Refer to GitHub's API documentation

🔗 Related Links

• Model Context Protocol

• GitHub API Documentation

• Octokit.js

• TypeScript

Happy coding! 🚀

Your GitHub MCP Server is ready with 10 powerful tools! You can:

• ✅ Get any repository information

• ✅ Search repositories with advanced filters

• ✅ List issues and pull requests

• ✅ Browse commit history

• ✅ Get user profiles and statistics

• ✅ Access your own GitHub data

• ✅ Use natural language queries