ai-agent-github-mcp-server

GitHub MCP Server

A Model Context Protocol (MCP) server for GitHub integration, enabling AI agents to review pull requests, read code for context, and interact with GitHub repositories.

Features

Pull Request Management

• List Pull Requests: Get all PRs with filtering by state, sort order, and pagination
• Get Pull Request Details: Retrieve comprehensive information about specific PRs
• Get Changed Files: See what files were modified in a PR
• Get PR Diff: Retrieve the unified diff for code review
• Create Reviews: Submit PR reviews with approval, change requests, or comments
• List Reviews: Get all reviews for a pull request

Repository Operations

• Repository Info: Get detailed repository information
• File Content: Read specific files from any branch or commit
• Directory Listing: Browse repository contents
• Code Search: Search for code across repositories with advanced queries
• Branch Management: List and inspect repository branches
• Commit Details: Get detailed information about specific commits

Issue Management

• List Issues: Get repository issues with comprehensive filtering
• Issue Details: Retrieve full information about specific issues
• Create Comments: Add comments to issues and pull requests
• List Comments: Get all comments on an issue

Installation

• Install dependencies:

npm install

• Build the server:

npm run build

Authentication

The server requires a GitHub Personal Access Token. You can create one at: https://github.com/settings/tokens

Required Scopes

For full functionality, your token should have these scopes:

• repo - Full control of private repositories (includes read access to public repos)
• read:user - Read user profile data
• read:org - Read organization membership (if working with org repos)

For public repositories only:

• public_repo - Access to public repositories

Environment Variables

Set your token as an environment variable:

# Option 1: GITHUB_TOKEN (recommended)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Option 2: GITHUB_API_KEY (alternative)
export GITHUB_API_KEY=ghp_xxxxxxxxxxxxxxxxxxxx

Usage

Running the Server

# Development mode
npm run dev

# Production mode
npm start

Integration with AI Agent Platform

Add to your agent's agent.yaml:

mcpServers:
  - name: github
    url: node ./mcp-servers/github/dist/server.js
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
    required: false  # Set to true if GitHub access is essential

Available Tools

Pull Request Tools

• github_list_pull_requests - List PRs for a repository
• github_get_pull_request - Get detailed PR information
• github_get_pull_request_files - Get files changed in a PR
• github_get_pull_request_diff - Get the unified diff
• github_create_pull_request_review - Create a PR review
• github_list_pull_request_reviews - List PR reviews

Repository Tools

• github_get_repository - Get repository information
• github_get_file_content - Read file contents
• github_list_repository_contents - List directory contents
• github_search_code - Search code with queries
• github_list_branches - List repository branches
• github_get_commit - Get commit details

Issue Tools

• github_list_issues - List repository issues
• github_get_issue - Get issue details
• github_create_issue_comment - Add comments to issues/PRs
• github_list_issue_comments - List issue comments

Example Usage

Review a Pull Request

// List open PRs
await tools.github_list_pull_requests({
  owner: "octocat",
  repo: "Hello-World",
  state: "open"
});

// Get PR details
await tools.github_get_pull_request({
  owner: "octocat",
  repo: "Hello-World",
  pull_number: 42
});

// Get the diff for review
await tools.github_get_pull_request_diff({
  owner: "octocat",
  repo: "Hello-World",
  pull_number: 42
});

// Create a review
await tools.github_create_pull_request_review({
  owner: "octocat",
  repo: "Hello-World",
  pull_number: 42,
  body: "Looks good to me! Just a few minor suggestions.",
  event: "APPROVE",
  confirm: true
});

Read Code for Context

// Get repository structure
await tools.github_list_repository_contents({
  owner: "octocat",
  repo: "Hello-World",
  path: "src"
});

// Read a specific file
await tools.github_get_file_content({
  owner: "octocat",
  repo: "Hello-World",
  path: "src/main.js",
  ref: "main"
});

// Search for specific code patterns
await tools.github_search_code({
  q: "function handleError repo:octocat/Hello-World"
});

Work with Issues

// List open issues
await tools.github_list_issues({
  owner: "octocat",
  repo: "Hello-World",
  state: "open",
  labels: "bug,high-priority"
});

// Add a comment to an issue
await tools.github_create_issue_comment({
  owner: "octocat",
  repo: "Hello-World",
  issue_number: 123,
  body: "I can reproduce this issue. Working on a fix.",
  confirm: true
});

Rate Limits

GitHub API has the following rate limits:

• Authenticated requests: 5,000 requests per hour
• Search API: 30 requests per minute
• Core API: 5,000 requests per hour

The server includes appropriate error handling for rate limit scenarios.

Error Handling

The server provides detailed error messages for common scenarios:

• Authentication failures
• Repository not found
• Pull request/issue not found
• Permission denied
• Rate limit exceeded
• Invalid parameters

Security Notes

• Never commit your GitHub token to version control
• Use environment variables or secure secret management
• Consider using fine-grained personal access tokens for better security
• Regularly rotate your access tokens
• Review token permissions and limit to minimum required scopes

Development

Project Structure

src/
├── server.ts              # Main MCP server entry point
├── auth/
│   └── api-key-manager.ts # GitHub token management
├── handlers/
│   ├── pull-requests.ts   # PR operations
│   ├── repository.ts      # Repository operations
│   └── issues.ts          # Issue operations
└── types/
    └── index.ts           # TypeScript type definitions

Building

npm run build

Testing

# Test the server directly
echo '{"method": "tools/list"}' | npm run dev

# Test with authentication
GITHUB_TOKEN=your_token npm run dev

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the GitHub API documentation: https://docs.github.com/en/rest
• Review rate limits and authentication requirements
• Ensure your token has the necessary scopes
• Check server logs for detailed error messages