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:

GITHUB_TOKEN=your_github_token_here
GITHUB_USERNAME=your_username_here  # Optional

🚀 Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

Watch Mode (for development)

npm run build:watch

Test the Server

npm test
npm run simple-test
npm run interactive-test
npm run demo

🛠 Tool Examples

User Information

Get Your GitHub Profile

{
  "tool": "get_my_info",
  "arguments": {}
}

Response:

👤 **My GitHub Profile**

**Username:** Om-Shree-0709
**Name:** Om Shree
**Bio:** Full Stack Developer
**Followers:** 25
**Following:** 50
**Public Repositories:** 15
**Profile URL:** https://github.com/Om-Shree-0709

Get User Information

{
  "tool": "get_user_info",
  "arguments": {
    "username": "microsoft"
  }
}

Repository Information

Get Repository Details

{
  "tool": "get_repo_info",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode"
  }
}

Response:

📁 **Repository: microsoft/vscode**

**Description:** Visual Studio Code
**Language:** TypeScript
**Visibility:** public
**Stars:** ⭐ 150000
**Forks:** 🍴 25000
**Watchers:** 👀 5000
**Created:** 1/1/2015
**Updated:** 12/15/2024
**URL:** https://github.com/microsoft/vscode

Search Repositories

{
  "tool": "search_repositories",
  "arguments": {
    "query": "language:typescript stars:>1000",
    "limit": 10
  }
}

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

{
  "tool": "list_repo_issues",
  "arguments": {
    "owner": "facebook",
    "repo": "react",
    "state": "open"
  }
}

List Pull Requests

{
  "tool": "list_repo_prs",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "state": "open"
  }
}

Commit History

List Recent Commits

{
  "tool": "list_repo_commits",
  "arguments": {
    "owner": "nodejs",
    "repo": "node",
    "limit": 20
  }
}

Statistics

Get User Statistics

{
  "tool": "get_github_stats",
  "arguments": {
    "username": "torvalds"
  }
}

Response:

📊 **GitHub Statistics for torvalds**

**User Info:**
• Followers: 50000
• Following: 0
• Public Repos: 1

**Repository Stats:**
• Total Repositories: 1
• Total Stars Received: ⭐ 200000
• Total Forks: 🍴 80000
• Average Stars per Repo: 200000.0

**Top Languages:**
C: 1

📚 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:

{
  "prompt": "github_query",
  "arguments": {
    "query": "Show me my most starred repositories"
  }
}

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:

# Required
GITHUB_TOKEN=your_github_token_here

# Optional
GITHUB_USERNAME=your_username_here

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

src/
├── server.ts          # Main server implementation with all tools and resources

dist/                  # Compiled JavaScript
node_modules/          # Dependencies

🔗 Integration

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/your/github-mcp-server/dist/server.js"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_repo_info",
    "arguments": {
      "owner": "microsoft",
      "repo": "vscode"
    }
  }
}

🛡 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

{"tool": "get_repo_info", "arguments": {"owner": "microsoft", "repo": "vscode"}}
{"tool": "list_repo_issues", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}}
{"tool": "list_repo_prs", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}}

2. User Analysis

{"tool": "get_user_info", "arguments": {"username": "torvalds"}}
{"tool": "get_github_stats", "arguments": {"username": "torvalds"}}
{"tool": "list_user_repos", "arguments": {"username": "torvalds", "type": "all"}}

3. Project Discovery

{"tool": "search_repositories", "arguments": {"query": "language:typescript stars:>1000"}}
{"tool": "search_repositories", "arguments": {"query": "topic:machine-learning created:>2023-01-01"}}

4. Your Own Data

{"tool": "get_my_info", "arguments": {}}
{"tool": "get_my_repos", "arguments": {"type": "all"}}
{"tool": "get_github_stats", "arguments": {"username": "Om-Shree-0709"}}

📝 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

# Build and test
npm run build
npm start

# Test with various scripts
npm test
npm run simple-test
npm run interactive-test
npm run demo

🚨 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:

npm run dev

📊 Response Format

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

{
  "content": [
    {
      "type": "text",
      "text": "📁 **Repository: microsoft/vscode**\n\n**Description:** Visual Studio Code\n**Stars:** ⭐ 150000\n..."
    }
  ]
}

🤝 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