GitHub MCP Server

An interactive Model Context Protocol (MCP) server for GitHub REST API integration with TypeScript.

Features

• Three GitHub tools: Search repositories, get repository issues, and search code
• SQLite caching: Reduces API calls with intelligent caching
• Rate limiting: Handles GitHub API rate limits gracefully
• No authentication required: Works with public repositories without tokens
• TypeScript: Full type safety and modern development experience

Tools

1. search_repos(username, query)

Search for repositories by username and query.

• Parameters:
  • username: GitHub username (default: environment variable GITHUB_USERNAME or "octocat")
  • query: Search query (default: "language:javascript")
• Example: Search Python repositories for user "octocat"

2. get_repo_issues(repo, state)

Get open issues for a repository.

• Parameters:
  • repo: Repository in format "owner/repo" (required)
  • state: Issue state - "open", "closed", or "all" (default: "open")
• Example: Get open issues from "microsoft/vscode"

3. search_code(repo, query)

Search code within a repository.

• Parameters:
  • repo: Repository in format "owner/repo" (required)
  • query: Code search query (required)
• Example: Search for "TODO" comments in "facebook/react"

Installation

Prerequisites

• Node.js 18+
• npm or yarn

Setup Steps

1. Clone or create the project directory:

   mkdir github-mcp-server
   cd github-mcp-server

2. Install dependencies:

   npm install

3. Set up environment variables (optional but recommended):

   # Create .env file
   touch .env
   
   # Add your GitHub username and token (token increases rate limits)
   echo "GITHUB_USERNAME=your-github-username" >> .env
   echo "GITHUB_TOKEN=ghp_your_token_here" >> .env

Getting a GitHub Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate new token (classic)
3. Select scopes:
   • repo (if you want to access private repositories)
   • public_repo (for public repositories only)
   • search (for search functionality)
4. Copy the token and add it to your .env file

Note: The server works without a token using public API (60 requests/hour limit). With a token, you get 5,000 requests/hour.

Usage

Development Mode

npm run dev

Production Mode

# Build the project
npm run build

# Start the server
npm start

Environment Variables

• GITHUB_USERNAME: Default GitHub username for searches
• GITHUB_TOKEN: GitHub personal access token (optional)

Example Queries

Search Repositories

// Search for Python repositories by a specific user
{
  "tool": "search_repos",
  "arguments": {
    "username": "octocat",
    "query": "language:python"
  }
}

// Search for repositories with "mcp" in name
{
  "tool": "search_repos", 
  "arguments": {
    "query": "mcp in:name"
  }
}

Get Repository Issues

// Get open issues from a popular repository
{
  "tool": "get_repo_issues",
  "arguments": {
    "repo": "microsoft/vscode"
  }
}

// Get all issues (open and closed) from a repository
{
  "tool": "get_repo_issues",
  "arguments": {
    "repo": "facebook/react",
    "state": "all"
  }
}

Search Code

// Search for TODO comments in a repository
{
  "tool": "search_code",
  "arguments": {
    "repo": "facebook/react",
    "query": "TODO"
  }
}

// Search for specific function definitions
{
  "tool": "search_code",
  "arguments": {
    "repo": "microsoft/vscode",
    "query": "function handleClick"
  }
}

// Search for import statements
{
  "tool": "search_code",
  "arguments": {
    "repo": "nodejs/node",
    "query": "import express"
  }
}

Rate Limiting

The server includes intelligent rate limiting:

• Without token: 60 requests per hour
• With token: 5,000 requests per hour
• Automatic handling: Waits when rate limits are reached
• Cache-first approach: Uses SQLite cache to minimize API calls
• Warning system: Alerts when approaching rate limits

Cache Strategy

• Search endpoints: 10-minute cache
• Repository data: 10-minute cache
• Issues: 5-minute cache
• General data: 5-minute cache

Caching

The server uses SQLite for caching to reduce API calls:

• Automatic cleanup: Removes expired entries
• Smart TTL: Different cache times for different endpoints
• Cache invalidation: Automatic when data expires

Cache File Location

• Default: ./cache.db
• Can be customized in the CacheManager constructor

Error Handling

The server handles various error scenarios:

• Rate limit exceeded: Automatically waits and retries
• Network errors: Graceful degradation with informative messages
• Invalid parameters: Clear error messages
• API errors: Detailed GitHub API error responses

Logging

All operations are logged to stderr for debugging:

• Rate limit warnings
• Cache operations
• API request/response info
• Error details

Development

Project Structure

src/
├── server.ts         # Main MCP server
├── github-client.ts  # GitHub API client with rate limiting
└── cache.ts         # SQLite caching layer

Building

npm run build

Cleaning

npm run clean

Troubleshooting

Common Issues

1. "Cannot find module" errors: Run npm install to install dependencies
2. Rate limit errors: Add a GitHub token or wait for reset
3. Permission errors: Check if cache.db file has write permissions
4. TypeScript errors: Ensure you have Node.js 18+ and TypeScript 5+

Debug Mode

Set environment variable for verbose logging:

DEBUG=github-mcp-server npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details