# GitHub MCP

> GitHub MCP Server manages repositories, tracks issues, and searches code via AI agents. Connect your GitHub account to your preferred AI client and automate core developer workflows—listing repos, getting file contents, or creating new issues—all from a natural conversation. Manage your entire software development lifecycle without leaving your chat window.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** version-control, repository-management, pull-requests, issue-tracking, code-search

## Description

**GitHub MCP Server** gives your AI client direct access to core GitHub functions. You'll use this server to manage repos, track issues, and search code right from your chat. You connect your GitHub account to your preferred AI client and automate core developer workflows—listing repos, getting file contents, or creating new issues—all without leaving your chat window. It's all about getting stuff done, fast. 

**View Repository Details and Lists**
You can list all repos owned by your user or a specific organization (`list_user_repositories`, `list_org_repositories`), or grab the specific metadata for any single project (`get_repository_details`). You can also see all forks associated with a project (`list_repository_forks`).

**Manage Issues and Pull Requests**
You can list all open issues for a repo (`list_repo_issues`) or list all pull requests, open or closed, for a repo (`list_pull_requests`). You can also open a new issue in a specific repository directly from your chat (`create_new_issue`).

**Search and Read Code Files**
You can run a powerful search for specific code snippets across the entire codebase using `search_github_code`. You can also search and list repositories by name or description across all of GitHub (`search_github_repositories`). Need to see what's in a file? Use `get_file_contents` to read the full text of any specified file. Finally, you can confirm your identity and permissions by retrieving your profile info (`get_my_github_profile`) or checking the API connection status (`verify_api_connection`).

## Tools

### add_issue_comment
Supports markdown formatting.

Add a comment to an issue or PR

### create_new_issue
Opens a new issue in a specific repository.

### create_pull_request
Requires the head branch (your changes) and base branch (merge target).

Create a pull request

### get_file_contents
Reads the full text content of a specified file.

### get_issue_details
Get a specific issue by number

### get_my_github_profile
Retrieves the authenticated user's GitHub profile information.

### get_repository_details
Fetches detailed metadata and configuration for a given repository.

### list_branches
List repository branches

### list_commits
Optionally filter by branch name or SHA.

List recent commits

### list_org_repositories
Lists all repositories owned by a specific organization.

### list_pull_requests
Lists all open and closed pull requests for a given repository.

### list_releases
List repository releases

### list_repo_issues
Lists all open issues for a specific repository.

### list_stargazers
Useful for popularity tracking.

List repository stargazers

### list_user_repositories
Lists all repositories owned by the authenticated user.

### search_github_code
Executes a powerful search for specific code snippets across the codebase.

### search_github_repositories
Searches and lists repositories by name or description across GitHub.

### verify_api_connection
Checks the connection status and validity of the GitHub API token.

## Prompt Examples

**Prompt:** 
```
List the last 5 open issues in the 'facebook/react' repository.
```

**Response:** 
```
Retrieving issues... I found 5 recent open issues in react, including 'Bug: Hydration error' and 'Feature request: New hook'. Would you like the details for any of them?
```

**Prompt:** 
```
Find all repositories for the organization 'vinkius'.
```

**Response:** 
```
Searching organization... I found 12 repositories for Vinkius, including 'vurb-core' and 'mcp-originals'. Would you like to see the stars count for these?
```

**Prompt:** 
```
Read the content of the 'README.md' file in 'vinkius/vurb-docs'.
```

**Response:** 
```
Fetching file... The README.md for vurb-docs contains: '# Vurb Documentation - Welcome to the official guide...'. Would you like me to summarize the installation steps?
```

## Capabilities

### View repository details and lists
List all repos for a user or organization, or fetch the specific metadata for a single project.

### Manage issues and pull requests
List open issues or pull requests for a repo, or programmatically create new issues from your chat.

### Search and read code files
Fetch the full text contents of any file or directory, or run targeted searches across the entire codebase.

### Track project growth and ownership
List all forks and contributors to a repository to gauge community interest and ownership.

### Identify user context and permissions
Retrieve the authenticated user's profile details to confirm permissions and project context.

## Use Cases

### The bug report is buried deep in the code.
A developer needs to find where a specific error handling function is used. They run `search_github_code` with the error signature. The agent returns all relevant file paths and snippets, letting them jump straight to the source code without searching through dozens of READMEs or file trees.

### The team needs a full list of all services.
A DevOps engineer needs to audit every service under the 'AcmeCorp' organization. They run `list_org_repositories`, which returns a clean, structured list of all 50 repositories, including metadata, allowing them to build an inventory quickly.

### A new feature needs to be tracked.
A PM decides a feature is needed. They use the agent to run `create_new_issue` with a detailed description and labels. The issue instantly appears in the target repository, and they get a link, all without opening the GitHub website.

### Checking the status of a big PR.
A developer asks the agent to `list_pull_requests` for a key repo. The agent checks the status, noting if it's approved, if conflicts exist, and who the last reviewer was. This replaces manually checking the PR dashboard.

## Benefits

- List all repos for an organization using `list_org_repositories` to immediately get a full inventory count, eliminating manual browsing through GitHub web interfaces.
- When you need to audit a project, `get_repository_details` provides immediate metadata—like last updated date and branch count—without needing to navigate the repo settings page.
- Instead of reading dozens of comments to find a bug, `search_github_code` lets you pinpoint a specific function signature or class definition across the entire codebase.
- Tracking project health is easy: `list_repo_issues` gives you a live count of open bugs, while `list_pull_requests` shows exactly which PRs are stuck waiting for review.
- You can initiate action instantly. Use `create_new_issue` to file a bug or request a feature without ever leaving your chat window.
- Audit project scope by calling `list_repository_forks` to see how many times the codebase has been adopted by the community.

## How It Works

The bottom line is, your AI client talks to GitHub, and you get the answer without opening a browser.

1. Subscribe to the GitHub MCP Server via Vinkius and enter your Personal Access Token.
2. Your AI client sends a request (e.g., 'List all PRs for vinkius/vurb-core').
3. The server executes the required GitHub API calls and returns structured data directly to your AI client.

## Frequently Asked Questions

**How do I get a Personal Access Token (PAT) for GitHub?**
Log in to GitHub, go to Settings > Developer settings > Personal access tokens, and you can generate a new token (classic or fine-grained) there.

**Can I read private repositories?**
Yes, provided that your Personal Access Token has the necessary scopes (e.g., 'repo') to access your private content.

**How do I search for code within a specific organization?**
Use the 'search_github_code' tool and include the organization qualifier in your query, for example: 'org:vinkius my-term'.

**Can I comment on issues via the agent?**
The current version supports creating new issues. For commenting or advanced PR management, you can use the search and metadata tools to gather context.

**How does the `get_file_contents` tool read file content?**
It fetches the raw text of the file. You just provide the full repository path and file name. The agent returns the content, which you can then analyze or summarize.

**What if I need to list all user repositories using `list_user_repositories`?**
You must specify the GitHub username. The tool returns a list of repository names and their primary metadata. This lets your AI client know what's available on that user's account.

**Does the GitHub MCP Server handle rate limits?**
Yes, the Vinkius platform manages rate limit adherence. When you make too many calls, the agent pauses and waits for the appropriate window reset, so your workflow doesn't fail.

**Can I check the connection status using `verify_api_connection`?**
This tool confirms that your Personal Access Token (PAT) is valid and authorized. It returns a success or failure status immediately, letting you know if the connection works before you start.