gh_mcp_server

This MCP server exposes a suite of GitHub operations as tools that can be invoked by MCP clients (for example Claude Desktop). It uses the GitHub CLI (gh) behind the scenes to perform repository, issue, pull request, workflow, release, and user operations, providing a structured JSON interface for each action. Typical usage involves configuring Claude (or another MCP client) to point at the running Java JAR, then issuing natural-language requests that map to the 26 available operations such as listing repositories, querying issues, creating pull requests, or retrieving commit histories. The server aims to be a lightweight, Docker-free alternative that relies on an authenticated gh setup and Spring Boot to return concise, machine-friendly results.

Prerequisites:\n- Java 21+ installed and available on the PATH\n- GitHub CLI (gh) installed and authenticated (gh auth login)\n- Gradle wrapper included in the project\n\nStep-by-step installation:\n1) Clone the repository:\n git clone <repository-url>\n2) Change into the project directory:\n cd gh_mcp_server\n3) Build the project using Gradle (wrapper included):\n ./gradlew build\n -> This will generate a jar such as gh_mcp_server-<version>.jar and also create a version-independent symlink gh_mcp_server.jar pointing to the current version.\n4) Run the server locally for testing (STDIO mode):\n ./gradlew bootRun\n (or run the built jar directly: java -jar build/libs/gh_mcp_server.jar)\n5) Configure Claude Desktop to use the MCP server:\n\nOption A: Using the JAR file (Recommended)\njson\n{\n "mcpServers": {\n "github": {\n "command": "java",\n "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],\n "env": {}\n }\n }\n}\n\nNote: A symlink gh_mcp_server.jar points to the current version (gh_mcp_server-1.0.0.jar). For version-specific deployment, use the full filename.\n\nOption B: Using Gradle\njson\n{\n "mcpServers": {\n "github": {\n "command": "./gradlew",\n "args": ["bootRun"],\n "cwd": "/path/to/gh_mcp_server",\n "env": {}\n }\n }\n}\n\n6) Restart Claude Desktop to load the new server configuration.

Tips and notes:\n- Ensure Java 21+ is installed and available in your PATH.\n- Ensure gh is installed and configured (gh auth status should show an authenticated session).\n- The server runs in STDIO mode by default for CLI integration; Claude Desktop handles the MCP protocol framing.\n- If the server fails to start, verify the path to gh_mcp_server.jar in your configuration and confirm Claude Desktop is restarted after changes.\n- The repository mentions 26 operations; common ones include listRepositories, getIssue, createIssue, listPRs, merge PRs, listWorkflows, listReleases, and getRepository details.\n- For local testing, you can run ./gradlew bootRun and supply commands via STDIN to exercise endpoints.\n- Environment variables can be added under the env map in the mcp_config to provide credentials or configuration as needed by your deployment environment.