GitHub API MCP Server

GitHub API MCP Server

The GitHub API MCP server provides a powerful interface to interact with GitHub repositories, issues, pull requests, and more through the GitHub API. This server enables AI assistants to perform a wide range of GitHub operations, from creating and updating files to searching code and managing issues.

Features

• Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
• Comprehensive Error Handling: Clear error messages for common GitHub API issues
• Git History Preservation: Operations maintain proper Git history without force pushing
• Batch Operations: Support for both single-file and multi-file operations
• Advanced Search: Search code, issues/PRs, and users across GitHub

Installation

To use the GitHub API MCP server, add the following configuration to your MCP client:

"mcpServers": {
  "github": {
    "url": "https://github-mcp-server.example.com"
  }
}

For local development, you can run the server using Docker:

docker pull modelcontextprotocol/github-server
docker run -p 3000:3000 -e GITHUB_TOKEN=your_github_token modelcontextprotocol/github-server

Then update your MCP client configuration to point to your local server:

"mcpServers": {
  "github": {
    "url": "http://localhost:3000"
  }
}

Authentication

The GitHub API MCP server requires a GitHub personal access token with appropriate permissions for the operations you want to perform. You can create a token in your GitHub account settings under Developer Settings > Personal Access Tokens.

For repository operations, you'll need the repo scope. For user operations, you'll need the user scope. For organization operations, you'll need the admin:org scope.

Usage Examples

Creating or Updating a File

// Create or update a file in a repository
const result = await github.create_or_update_file({
  owner: "username",
  repo: "repository-name",
  path: "path/to/file.txt",
  content: "File content goes here",
  message: "Add or update file",
  branch: "main"
});

Creating a Pull Request

// Create a pull request
const pr = await github.create_pull_request({
  owner: "username",
  repo: "repository-name",
  title: "Add new feature",
  body: "This PR adds a new feature",
  head: "feature-branch",
  base: "main"
});

Searching Code

// Search for code
const searchResults = await github.search_code({
  q: "function in:file language:javascript repo:username/repository-name"
});

Error Handling

The GitHub API MCP server provides detailed error messages for common issues. If you encounter an error, check the error message for details on what went wrong and how to fix it.

Common errors include:

• Authentication errors (invalid or expired token)
• Permission errors (insufficient permissions for the requested operation)
• Rate limiting (GitHub API rate limits exceeded)
• Resource not found (repository, file, issue, etc. not found)

Limitations

• The GitHub API has rate limits that apply to this MCP server. For authenticated requests, the rate limit is 5,000 requests per hour.
• Some operations may require specific permissions that your GitHub token may not have.
• Large file operations may be limited by GitHub's file size restrictions.

Additional Resources

• GitHub API Documentation
• GitHub Search Syntax