Integrate GitHub functionalities into AI assistants using the GitHub CLI.
A Spring Boot-based Model Context Protocol (MCP) server that provides GitHub integration tools for AI assistants like Claude Desktop.
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.
To use this server with Claude Desktop, add the following to your Claude configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"github": {
"command": "java",
"args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
"env": {}
}
}
}
Replace /path/to/gh_mcp_server with the actual path to your project directory.
gh) - Must be installed and authenticatedInstall GitHub CLI
# macOS
brew install gh
# or download from https://cli.github.com/
Authenticate with GitHub
gh auth login
Clone and build the project
git clone <repository-url>
cd gh_mcp_server
./gradlew build
Note: The build automatically creates a version-independent symlink
gh_mcp_server.jar→gh_mcp_server-1.0.0.jar
Configure Claude Desktop
After building, configure Claude to use this MCP server. You have two options:
Option A: Using the JAR file (Recommended)
{
"mcpServers": {
"github": {
"command": "java",
"args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
"env": {}
}
}
}
Note: A symlink
gh_mcp_server.jarpoints to the current version (gh_mcp_server-1.0.0.jar). This provides version-independent deployment. For version-specific deployment, use the full versioned filename instead.
Option B: Using Gradle
{
"mcpServers": {
"github": {
"command": "./gradlew",
"args": ["bootRun"],
"cwd": "/path/to/gh_mcp_server",
"env": {}
}
}
}
Restart Claude Desktop to load the new server configuration
After configuring Claude Desktop, you can use natural language to interact with GitHub:
If the server fails to start, check that:
gh auth status)To test the server independently (without Claude):
./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.
# 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
The project includes comprehensive test coverage:
gh command constructionSee src/test/java/com/kousenit/gh_mcp_server/TEST_README.md for detailed testing documentation.
The server uses Spring Boot's default configuration. You can customize settings in src/main/resources/application.properties.
github.defaultBranch - Default branch name for operations (default: main)spring.threads.virtual.enabled - Enable virtual threads for better performance (default: true)listRepositories - List user's repositories with optional visibility filter (public/private/internal)searchRepositories - Search GitHub repositoriesgetRepository - Get detailed repository informationgetCommitHistory - Get repository commit history with configurable limitlistBranches - List repository branchescreateBranch - Create a new branchlistIssues - List issues in repositorygetIssue - Get specific issue detailscreateIssue - Create new issuecloseIssue - Close an issuecommentOnIssue - Add comment to issueeditIssue - Edit issue title/bodylistPullRequests - List pull requestsgetPullRequest - Get PR detailscreatePullRequest - Create new pull requestmergePullRequest - Merge PR (merge/squash/rebase)closePullRequest - Close pull requestcommentOnPullRequest - Add PR commentlistWorkflows - List repository workflowslistWorkflowRuns - List workflow runs with filteringgetWorkflowRun - Get workflow run detailslistReleases - List repository releasesgetRelease - Get release detailscreateRelease - Create new release (draft/prerelease options)getFileContents - Get file contents from repositorygetMe - Get authenticated user detailsAll operations return optimized JSON responses and support comprehensive error handling.
"gh: command not found"
gh is in your system PATHgh --versionAuthentication errors
gh auth login to authenticategh auth statusServer startup failures
java --versionCommand timeouts
Permission denied errors
gh helpThe build process generates JAR files with version numbers in the filename (e.g., gh_mcp_server-1.0.0.jar). When deploying or updating:
Initial Deployment: Use the current version in your Claude Desktop configuration:
"args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server-1.0.0.jar"]
Version Updates: When updating to a new version, you must:
./gradlew buildVersion-Independent Deployment: For easier deployment, you can:
gh_mcp_server.jar (created automatically during build)Automatic Symlink Management: The build process automatically creates and maintains the symlink:
./gradlew build creates gh_mcp_server.jar → gh_mcp_server-X.Y.Z.jar./gradlew clean build recreates the symlink with the correct versionString.formatted() for cleaner string constructionThis project is licensed under the MIT License - see the LICENSE file for details.
Manage GitHub Projects V2 using the GitHub GraphQL API.
An MCP server for performing Git operations.
A server for GitHub project management with advanced resource management, capacity planning, and workload optimization capabilities.
Integrates with GitHub, allowing LLMs to interact with repositories, issues, and pull requests via the GitHub API.
Integrate with the GitHub Enterprise API to access repositories, issues, pull requests, and workflows.
Allows AI assistants to interact with the GitHub API for repository management, code collaboration, and other development tasks.
Perform Git operations on Azure DevOps repositories using a Personal Access Token (PAT).
Gitee API integration, repository, issue, and pull request management, and more.
A GitLab integration server providing access to GitLab's RESTful API tools, built on the fastmcp framework.
Manage GitHub projects with requirements traceability and advanced workflows.