Github

This MCP server provides an interface for AI assistants to manage GitHub repositories, issues, pull requests, branches, and files via natural language. It exposes 15 tools organized into repository, issue, pull request, branch, and file operations. Examples include listing repositories, creating issues, fetching PR details, creating branches, and reading or updating files within a repository. To use it, run the server with the required GitHub credentials loaded from environment variables, then interact with the MCP SDK-enabled client to issue high-level intents (e.g., “List all my repositories” or “Create a pull request to merge feature-x”). The server translates natural language prompts into specific GitHub API calls and returns structured results that your agent can present to users.

Once running, you can invoke tools by forming MCP messages that reference actions like list_repositories, create_issue, create_branch, get_file_contents, or merge_pull_request. The server authenticates to GitHub using the provided GITHUB_TOKEN, performs the requested action, and returns data such as repository lists, issue details, PR statuses, or file contents. Use the included examples and tests as guidance for crafting prompts that map to the available tools.

Additionally, the server supports standard MCP workflows and error handling. If a requested operation requires additional context (e.g., creating an issue with a title and body), ensure your prompt includes the necessary fields or leverage the server’s ability to prompt for missing details via the MCP protocol.

Prerequisites:

• Python 3.11+ installed on your system
• Git installed (for cloning the repository)
• Internet access to download dependencies from PyPI

Step-by-step installation:

1. Clone the repository

git clone https://github.com/afrah123456/github-mcp-server.git
cd github-mcp-server

2. Create and activate a Python virtual environment (optional but recommended)

python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Prepare environment (GitHub token)

cp .env.example .env

Edit .env to include your GitHub credentials:

GITHUB_TOKEN=your_github_token_here
GITHUB_USERNAME=your_username

5. Run the server

python run_server.py

6. Verify installation with tests (optional)

pytest tests/ -v

Notes:

• Ensure network access to GitHub and that the token has appropriate scopes (repo, user, delete_repo).
• If you modify configuration or environment, restart the server to apply changes.

Tips and common issues:

• Ensure GITHUB_TOKEN has sufficient scopes for the actions you intend to perform (repo, user, delete_repo).
• If the server cannot authenticate, double-check environment variables and that .env is loaded correctly by your runtime.
• The server relies on PyGithub; verify PyGithub compatibility with your Python version.
• Use descriptive prompts to reduce ambiguity (e.g., specify repository names, issue titles, or PR numbers explicitly).
• For destructive actions (like close_issue or merge_pull_request), consider adding confirmation prompts or additional context in prompts to prevent unintended changes.