Labsco
kousen logo

GitHub MCP Server

★ 6

from kousen

Integrate GitHub functionalities into AI assistants using the GitHub CLI.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#devops#git

GitHub MCP Server

A Spring Boot-based Model Context Protocol (MCP) server that provides GitHub integration tools for AI assistants like Claude Desktop.

Overview

This server implements the Model Context Protocol to expose GitHub operations as tools that can be used by MCP clients. It leverages the GitHub CLI (gh) to perform various GitHub operations including repository management, issue tracking, pull request management, and more. This provides a lightweight alternative to the official GitHub MCP server that doesn't require Docker.

Features

Repository Operations

  • List repositories for authenticated user
  • Search repositories on GitHub
  • Get detailed repository information
  • List branches in a repository
  • Create new branches
  • Get file contents from repositories
  • Get commit history

Issue Management

  • List issues (open, closed, or all)
  • Get detailed issue information
  • Create new issues
  • Close issues
  • Add comments to issues
  • Edit issue title and body

Pull Request Management

  • List pull requests
  • Get detailed pull request information
  • Create new pull requests
  • Merge pull requests (merge, squash, or rebase)
  • Close pull requests
  • Add comments to pull requests

Workflow and Actions

  • List workflows in a repository
  • List workflow runs with optional filtering
  • View detailed workflow run information

Release Management

  • List releases
  • View release details
  • Create new releases (with draft/prerelease options)

User Operations

  • Get authenticated user details

Why Use This MCP Server?

  • 🚀 Lightweight: No Docker required, pure Java implementation
  • 🔧 Comprehensive: 26 GitHub operations covering complete workflows
  • ⚡ Fast: Direct GitHub CLI integration with optimized JSON responses
  • 🧪 Well-Tested: 75+ test cases ensuring reliability
  • 🛡️ Secure: Leverages existing GitHub CLI authentication

Verification

If the server fails to start, check that:

  • Java 21+ is installed and in your PATH
  • GitHub CLI is installed and authenticated (gh auth status)
  • The JAR file path in the configuration is correct
  • Claude Desktop has been restarted

Testing the Server

To test the server independently (without Claude):

Copy & paste — that's it
./gradlew bootRun

The server will start in STDIO mode and wait for MCP protocol messages. However, for normal usage, the server should be configured to run automatically by Claude Desktop as shown above.

Development Commands

Copy & paste — that's it
# Build the project and run all tests
./gradlew build

# Run tests (command syntax validation only)
./gradlew test

# Run tests including GitHub CLI integration tests
./gradlew test -Dtest.gh.integration=true

# Format code with Spotless (Google Java Format)
./gradlew spotlessApply

# Check code formatting without applying changes
./gradlew spotlessCheck

# Clean build artifacts
./gradlew clean

# Run the server locally for testing
./gradlew bootRun

Test Coverage

The project includes comprehensive test coverage:

  • 75+ test cases validating all 26 GitHub operations
  • Command syntax tests - Verify exact gh command construction
  • Edge case tests - Handle special characters, Unicode, null values
  • Integration tests - Optional real GitHub CLI execution
  • Error handling tests - Validate graceful failure modes

See src/test/java/com/kousenit/gh_mcp_server/TEST_README.md for detailed testing documentation.

Available Operations (26 Total)

Repository Operations

  • listRepositories - List user's repositories with optional visibility filter (public/private/internal)
  • searchRepositories - Search GitHub repositories
  • getRepository - Get detailed repository information
  • getCommitHistory - Get repository commit history with configurable limit
  • listBranches - List repository branches
  • createBranch - Create a new branch

Issue Management

  • listIssues - List issues in repository
  • getIssue - Get specific issue details
  • createIssue - Create new issue
  • closeIssue - Close an issue
  • commentOnIssue - Add comment to issue
  • editIssue - Edit issue title/body

Pull Request Management

  • listPullRequests - List pull requests
  • getPullRequest - Get PR details
  • createPullRequest - Create new pull request
  • mergePullRequest - Merge PR (merge/squash/rebase)
  • closePullRequest - Close pull request
  • commentOnPullRequest - Add PR comment

Workflow & CI/CD

  • listWorkflows - List repository workflows
  • listWorkflowRuns - List workflow runs with filtering
  • getWorkflowRun - Get workflow run details

Release Management

  • listReleases - List repository releases
  • getRelease - Get release details
  • createRelease - Create new release (draft/prerelease options)

File & User Operations

  • getFileContents - Get file contents from repository
  • getMe - Get authenticated user details

All operations return optimized JSON responses and support comprehensive error handling.

Technology Stack

  • Spring Boot 3.5.0 - Application framework
  • Spring AI 1.0.0 - AI integration and MCP server capabilities
  • Java 21 - Programming language with virtual threads support
  • GitHub CLI - GitHub API integration
  • Gradle - Build tool
  • Spotless - Code formatting with Google Java Format

Key Implementation Features

  • Virtual Threads (Java 21) - Efficient concurrent I/O operations
  • ProcessBuilder - Secure command execution with timeout support
  • Records (Java 17) - Immutable data structures for command results
  • Pattern Matching - Modern Java syntax for type checking
  • String Templates - Using String.formatted() for cleaner string construction

License

This project is licensed under the MIT License - see the LICENSE file for details.