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

Clone the repository:

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

Install dependencies:
```
npm install
```

Set up environment variables:

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

Build the project:
```
npm run build
```

🔑 GitHub Token Setup

Go to GitHub Settings > Personal Access Tokens
Click "Generate new token (classic)"
Select the following scopes:
- repo (Full control of private repositories)
- user (Read all user profile data)
- read:org (Read org and team membership)
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

Create a new function in src/server.ts
Register the tool with server.registerTool()
Add proper error handling
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

"Cannot find module" errors
- Run npm install to install dependencies
- Run npm run build to compile TypeScript
Authentication failures
- Check your GitHub token is valid
- Ensure token has required scopes
- Verify .env file exists and is readable
Rate limit errors
- Wait before making more requests
- Consider using a token with higher rate limits
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

Fork the repository
Create a feature branch
Add your changes
Test thoroughly
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

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

GitHub MCP TypeScript SDK Server

🚀 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

Clone the repository:

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

Install dependencies:
```
npm install
```

Set up environment variables:

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

Build the project:
```
npm run build
```

🔑 GitHub Token Setup

Go to GitHub Settings > Personal Access Tokens
Click "Generate new token (classic)"
Select the following scopes:
- repo (Full control of private repositories)
- user (Read all user profile data)
- read:org (Read org and team membership)
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

Create a new function in src/server.ts
Register the tool with server.registerTool()
Add proper error handling
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

"Cannot find module" errors
- Run npm install to install dependencies
- Run npm run build to compile TypeScript
Authentication failures
- Check your GitHub token is valid
- Ensure token has required scopes
- Verify .env file exists and is readable
Rate limit errors
- Wait before making more requests
- Consider using a token with higher rate limits
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

Fork the repository
Create a feature branch
Add your changes
Test thoroughly
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

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

GitHub MCP TypeScript SDK Server

GitHub MCP TypeScript SDK Server

🚀 Features

📋 Available Tools (10 Total)

🔧 Capabilities

📦 Installation

Prerequisites

Setup

🔑 GitHub Token Setup

🚀 Usage

Development Mode

Production Mode

Watch Mode (for development)

Test the Server

🛠 Tool Examples

User Information

Get Your GitHub Profile

Get User Information

Repository Information

Get Repository Details

Search Repositories

Issues and Pull Requests

List Repository Issues

List Pull Requests

Commit History

List Recent Commits

Statistics

Get User Statistics

📚 Resources

Repository Resource

User Resource

💬 Prompts

Natural Language Queries

🔧 Configuration

Environment Variables

GitHub Token Scopes

🏗 Architecture

Project Structure

🔗 Integration

With Claude Desktop

With Other MCP Clients

Direct JSON-RPC Usage

🛡 Error Handling

📈 Performance Features

🎯 Practical Use Cases

1. Repository Research

2. User Analysis

3. Project Discovery

4. Your Own Data

📝 Development

Available Scripts

Adding New Tools

Testing

🚨 Troubleshooting

Common Issues

Debug Mode

📊 Response Format

🤝 Contributing

📄 License

🆘 Support

🔗 Related Links

GitHub MCP TypeScript SDK Server

🚀 Features

📋 Available Tools (10 Total)

🔧 Capabilities

📦 Installation

Prerequisites

Setup

🔑 GitHub Token Setup

🚀 Usage

Development Mode

Production Mode

Watch Mode (for development)

Test the Server

🛠 Tool Examples

User Information

Get Your GitHub Profile

Get User Information

Repository Information

Get Repository Details