MCPGithub 🚀

Description 📝

MCPGithub is a GitHub repository management tool integrated with the Model Context Protocol (MCP). This project allows you to interact with the GitHub API efficiently and securely, facilitating repository, branch, and pull request management for any GitHub repository you have access to.

Features ✨

• 📦 Repository management (create, list, delete)
• 🌿 Branch control (create, list, delete)
• 🔄 Pull Request handling
• 🔐 Secure token authentication
• ⚡ MCP integration for a smooth experience
• 🌐 Multi-repository support (work with any GitHub repository)
• 📊 JSON-structured responses for better integration
• 🧩 Consistent error handling

Prerequisites 📋

• Python 3.x
• GitHub account
• GitHub token with necessary permissions
• Configured environment variables

Environment Variables Configuration (.env) ⚙️

This project uses a .env file to manage sensitive environment variables, such as the GitHub token. The server validates the existence, readability, and content of the .env file before starting. If the file is missing, unreadable, empty, or the GITHUB_TOKEN is missing, the server will display a clear error message and will not continue execution.

Example of a .env file:

GITHUB_TOKEN=your_personal_github_token
GITHUB_USERNAME=your_github_username
GITHUB_DEFAULT_BRANCH=master
GITHUB_REPOSITORY=default_repository_name

Place the .env file in the root of the project (MCPGithub/).

Note: While default values are provided in the .env file, you can override them in any function call to work with different repositories.

Installation 🛠️

1. Clone the repository:

git clone https://github.com/alvnavraii/MCPGithub.git

2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file in the root of the project with the required content.

Usage 💻

The project runs as an MCP server and provides tools for managing GitHub repositories with consistent JSON-structured responses.

Repository Management

• list_repositories() 📚: Lists all repositories owned by the authenticated user
• create_repository(repository_name, private=True) ➕: Creates a new repository with optional privacy setting
• delete_repository(repository_name=None, repository_full_name=None) ❌: Deletes an existing repository using either name or full name (username/repository)
• get_repository_info(repository_full_name) ℹ️: Gets detailed information about any repository

Branch Management

• list_branches(repository_full_name) 🌳: Lists all branches in a specified repository
• create_branch(repository_full_name, branch_name, source_branch="master") 🌱: Creates a new branch from a source branch
• delete_branch(repository_full_name, branch_name, token) 🗑️: Force deletes a branch from the repository

Pull Request Management

• create_pull_request(repository_full_name, head_branch, base_branch) 🔄: Creates a new pull request
• list_pull_requests(repository_full_name) 📋: Lists all open pull requests in a repository
• merge_pull_request(repository_full_name, pull_request_number) 🔀: Merges a pull request if it's mergeable

Commit Management

• list_commits(repository_full_name, branch="master") 📜: Lists all commits in a specified branch

Issue Management

• create_issue(repository_full_name, title, body) 📝: Creates a new issue in the specified repository

Git Operations

• git_add(repo_path=".") ➕: Stages all changes in the repository
• git_commit(message="First Commit", repo_path=".") ✔️: Commits staged changes with a message
• git_push(branch="master", repo_path=".", token=None, usuario=None, repo_name=None, repository_full_name=None) ⬆️: Pushes commits to any remote repository

Working with Any Repository 🌐

Specifying Repositories

All functions that interact with GitHub repositories now accept a repository_full_name parameter in the format "username/repository". This allows you to work with any repository you have access to, not just the default one specified in your .env file.

Examples:

# List commits from a specific repository
list_commits(repository_full_name="octocat/Hello-World")

# Create a pull request in any repository you have access to
create_pull_request(
    repository_full_name="your-org/your-project", 
    head_branch="feature-branch", 
    base_branch="main"
)

# Get detailed information about any public repository
get_repository_info(repository_full_name="tensorflow/tensorflow")

Structured JSON Responses

All functions now return structured JSON responses with a consistent format:

• Success responses: {"result": {...}} containing the operation result data
• Error responses: {"error": "error message"} with details about what went wrong

This consistent format makes it easier to handle responses programmatically and implement error handling in your applications.

Troubleshooting and Configuration Validation ⚠️

When starting the server, the following validations are performed:

• 🗂️ Checks that the .env file exists in the project root.
• 👁️ Ensures the .env file is readable.
• 📄 Ensures the .env file is not empty.
• 🛡️ Validates that the GITHUB_TOKEN variable is present and not empty.

Common Error Messages

• ❗ .env file not found at ...: The .env file does not exist at the expected path.
• ❗ .env file is not readable at ...: The file exists but does not have read permissions.
• ❗ .env file is empty: The file exists but is empty.
• ❗ GITHUB_TOKEN not loaded from .env file: The GITHUB_TOKEN variable is missing or empty.

If you encounter any of these errors, check the existence, permissions, and content of your .env file.

Startup and Validation Flow ⚙️

When running the server, it first loads and validates the .env file. If everything is correct, the GitHub client is initialized and the MCP server starts. If any validation error occurs, the server displays a descriptive message and will not continue execution.

MCP Server Configuration 🔧

Claude Desktop Configuration 🤖

1. Locate the Claude configuration file:

~/.config/Claude/claude_desktop_config.json

2. Add the MCP server configuration in the mcpServers section (only command and args are required):

{
  "mcpServers": {
    "GitHubManagement": {
      "command": "/path/to/your/venv/python",
      "args": [
        "/path/to/your/project/MCPGithub/server.py"
      ]
    }
  }
}

Note: All sensitive data (username, token, defaultBranch, etc.) is now managed exclusively via the .env file in your project root. Do not include these fields in the JSON configuration.

Windsurf Desktop Configuration 🌊

1. Locate the Windsurf configuration file:

~/.config/Windsurf/windsurf_desktop_config.json

2. Add the MCP server configuration in the mcpServers section (only command and args are required):

{
  "mcpServers": {
    "GitHubManagement": {
      "command": "/path/to/your/venv/python",
      "args": [
        "/path/to/your/project/MCPGithub/server.py"
      ]
    }
  }
}

Note: All credentials and configuration details are handled via the .env file. The JSON should only specify how to launch the MCP server.

Security 🔒

• Tokens are handled through environment variables
• Secure authentication implementation
• Permission and access validation
• Repository access limited to user permissions

Contributing 🤝

Contributions are welcome. Please make sure to:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License 📄

This project is under the MIT License. See the LICENSE file for more details.

Author ✍️

• Rafael Álvarez Navarrete - @alvnavraii

Acknowledgments 💎

• GitHub API
• MCP Framework
• All contributors