{"id":27598629,"url":"https://github.com/stephanj/githubmcp","last_synced_at":"2025-08-09T21:11:13.984Z","repository":{"id":287369011,"uuid":"964467977","full_name":"stephanj/GitHubMCP","owner":"stephanj","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-11T13:15:50.000Z","size":31,"stargazers_count":26,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T14:15:26.934Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stephanj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-11T09:02:45.000Z","updated_at":"2025-04-22T11:55:56.000Z","dependencies_parsed_at":"2025-04-11T12:04:02.607Z","dependency_job_id":"13a71b9f-aac1-4bdc-91e6-0c8aca85ca68","html_url":"https://github.com/stephanj/GitHubMCP","commit_stats":null,"previous_names":["stephanj/githubmcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephanj%2FGitHubMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephanj%2FGitHubMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephanj%2FGitHubMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephanj%2FGitHubMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephanj","download_url":"https://codeload.github.com/stephanj/GitHubMCP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250255770,"owners_count":21400410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-22T14:15:32.443Z","updated_at":"2025-04-22T14:15:32.978Z","avatar_url":"https://github.com/stephanj.png","language":"Java","readme":"# GitHub MCP Server\n\nThis project implements a Model Context Protocol (MCP) server for GitHub API access. It provides a set of tools that allow LLM agents to interact with GitHub repositories, issues, pull requests, and other GitHub resources.\n\n## Features\n\nThe server provides the following GitHub operations:\n\n- **Repository Management**\n  - List repositories for the authenticated user\n  - Get repository details\n  - Search for repositories\n\n- **Issue Management**\n  - List issues with filtering options\n  - Get detailed information about issues\n  - Create new issues\n  - Add comments to issues\n  - Search for issues\n\n- **Pull Request Management**\n  - List pull requests with filtering options\n  - Get detailed information about pull requests\n  - Create comments on pull requests\n  - Merge pull requests\n\n- **Branch Management**\n  - List branches in a repository\n  - Create new branches\n\n- **Commit Management**\n  - Get detailed information about commits\n  - List commits with filtering options\n  - Search for commits by message\n\n- **Content Management**\n  - Get file contents from repositories\n  - List directory contents\n  - Create or update files\n  - Search for code within repositories\n\nThese operations are exposed as tools for Large Language Models using the Model Context Protocol (MCP), allowing AI systems to safely interact with GitHub through its API.\n\n### Claude Desktop\n\u003cimg width=\"931\" alt=\"GitHubExample\" src=\"https://github.com/user-attachments/assets/aa39e8d3-7443-41c7-888f-640680a3a297\" /\u003e\n\n### DevoxxGenie IDEA plugin\n\u003cimg width=\"894\" alt=\"Screenshot 2025-04-11 at 12 32 58\" src=\"https://github.com/user-attachments/assets/06a66881-0ca6-494e-814d-cafe97e870cc\" /\u003e\n\n\n## Getting Started\n\n### Prerequisites\n\n- Java 17 or higher\n- Maven 3.6+\n- Spring Boot 3.3.6\n- Spring AI MCP Server components\n- A GitHub account and personal access token\n\n### Building the Project\n\nBuild the project using Maven:\n\n```bash\nmvn clean package\n```\n\n### Running the Server\n\nRun the server using the following command:\n\n```bash\njava -jar target/GitHubMCP-1.0-SNAPSHOT.jar\n```\n\nThe server can use STDIO for communication with MCP clients or can be run as a web server.\n\n## Environment Variables\n\nThe GitHub MCP server supports the following environment variables for authentication:\n\n- `GITHUB_TOKEN` or `GITHUB_PERSONAL_ACCESS_TOKEN`: Your GitHub personal access token\n- `GITHUB_HOST`: The base URL of your GitHub instance (e.g., `github.com` or `github.mycompany.com` for GitHub Enterprise)\n- `GITHUB_REPOSITORY`: Default repository to use if not specified in API calls (e.g., `owner/repo`)\n\nYou can set these environment variables when launching the MCP server, and the GitHub services will use them as default values. This allows you to avoid having to provide authentication details with every API call.\n\n## Usage with MCP Clients\n\n### Using with Claude Desktop\n\nEdit your claude_desktop_config.json file with the following:\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"java\",\n      \"args\": [\n        \"-Dspring.ai.mcp.server.stdio=true\",\n        \"-Dspring.main.web-application-type=none\",\n        \"-Dlogging.pattern.console=\",\n        \"-jar\",\n        \"/path/to/GitHubMCP/target/GitHubMCP-1.0-SNAPSHOT.jar\"\n      ],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"your-github-token-here\",\n        \"GITHUB_HOST\": \"github.com\",\n        \"GITHUB_REPOSITORY\": \"your-username/your-repository\"\n      }\n    }  \n  }\n}\n```\n\n### Using with DevoxxGenie or similar MCP clients\n\n1. In your MCP client, access the MCP Server configuration screen\n2. Configure the server with the following settings:\n   - **Name**: `GitHub` (or any descriptive name)\n   - **Transport Type**: `STDIO`\n   - **Command**: Full path to your Java executable\n   - **Arguments**:\n     ```\n     -Dspring.ai.mcp.server.stdio=true\n     -Dspring.main.web-application-type=none\n     -Dlogging.pattern.console=\n     -jar\n     /path/to/GitHubMCP/target/GitHubMCP-1.0-SNAPSHOT.jar\n     ```\n   - **Environment Variables**:\n     ```\n     GITHUB_TOKEN=your-github-token-here\n     GITHUB_HOST=github.com\n     GITHUB_REPOSITORY=your-username/your-repository\n     ```\n\n## Security Considerations\n\nWhen using this server, be aware that:\n- You need to provide a GitHub personal access token for authentication\n- The LLM agent will have access to create, read, and modify GitHub resources\n- Consider running the server with appropriate permissions and in a controlled environment\n- Ensure your token has only the minimum required permissions for your use case\n\n## Example Usage\n\n### With Environment Variables\n\nIf you've configured the MCP server with environment variables, you can simply ask:\n\n```\nCan you get a list of open issues in my GitHub repository?\n```\n\nClaude will use the GitHub services with the pre-configured authentication details to fetch the open issues from your GitHub repository and summarize them.\n\n### With Explicit Repository\n\nYou can override the default repository by specifying it in your request:\n\n```\nCan you list the pull requests for the anthropics/claude-playground repository?\n```\n\nThe GitHub service will use your authentication token but query the specified repository instead of the default one.\n\n## Available Services\n\nThe GitHub MCP server is organized into several service classes, each providing different functionality:\n\n1. **RepositoryService**\n   - `listRepositories`: List repositories for the authenticated user\n   - `getRepository`: Get detailed information about a specific repository\n   - `searchRepositories`: Search for repositories matching a query\n\n2. **IssueService**\n   - `listIssues`: List issues for a repository with filtering options\n   - `getIssue`: Get detailed information about a specific issue\n   - `createIssue`: Create a new issue in a repository\n   - `addIssueComment`: Add a comment to an issue\n   - `searchIssues`: Search for issues matching a query\n\n3. **PullRequestService**\n   - `listPullRequests`: List pull requests for a repository with filtering options\n   - `getPullRequest`: Get detailed information about a specific pull request\n   - `createPullRequestComment`: Add a comment to a pull request\n   - `mergePullRequest`: Merge a pull request with specified merge method\n\n4. **BranchService**\n   - `listBranches`: List branches in a repository with filtering options\n   - `createBranch`: Create a new branch from a specified reference\n\n5. **CommitService**\n   - `getCommitDetails`: Get detailed information about a specific commit\n   - `listCommits`: List commits in a repository with filtering options\n   - `findCommitByMessage`: Search for commits containing specific text in their messages\n\n6. **ContentService**\n   - `getFileContents`: Get the contents of a file in a repository\n   - `listDirectoryContents`: List contents of a directory in a repository\n   - `createOrUpdateFile`: Create or update a file in a repository\n   - `searchCode`: Search for code within repositories\n\nEach service provides methods that can be called by LLM agents through the MCP protocol, allowing them to interact with GitHub in a structured and controlled manner.\n\n## Enterprise GitHub Support\n\nThis MCP server supports both GitHub.com and GitHub Enterprise instances. To use with GitHub Enterprise, set the `GITHUB_HOST` environment variable to your enterprise GitHub URL.\n\n## Limitations\n\n- The server requires a valid GitHub personal access token with appropriate permissions\n- Rate limiting is subject to GitHub API limits\n- Some operations may require specific permissions on the token\n- Large repositories or files may encounter performance limitations\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","funding_links":[],"categories":["Repository \u0026 Code Analysis MCP Servers","Version Control"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephanj%2Fgithubmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephanj%2Fgithubmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephanj%2Fgithubmcp/lists"}