Skip to main content
Glama
deenesjakoruzh
LeonidYasin

MCP GitHub Server

by LeonidYasin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP GitHub Server

Extensible MCP HTTP server for the GitHub API with a modular architecture and automatic tool discovery.

Features

The server provides 19 tools for working with GitHub:

📁 File operations (4)

Tool

Description

get_file_contents

Reading file contents from a repository

create_or_update_file

Creating and updating text files

create_or_update_binary_file

Creating and updating binary files (base64)

delete_file

Deleting files (automatically obtains SHA)

📝 Commits (2)

Tool

Description

list_commits

List of recent commits

get_commit_status

Check status for a commit

⚙️ Workflow (7)

Tool

Description

get_latest_workflow_error

Error from the latest build

get_workflow_run_logs

Logs of a specific workflow run

get_full_workflow_logs

Full logs of all jobs in a run

get_workflow_by_file

Workflow runs by YAML file name

list_workflow_runs

List of runs with run_id and statuses

get_latest_run_id

run_id of the latest run

get_workflow_run_steps

List of all steps in a run with their statuses

🏗️ Build and debugging (6)

Tool

Description

watch_build

Build monitoring

auto_fix_build

Auto-fix build errors (Android/iOS)

get_android_build_error

Detailed Android build error

get_ios_build_error

Detailed iOS build error

get_run_logs_by_step

Logs of a specific step by name

create_or_update_file_with_sha

Create/update with auto-obtaining SHA

Related MCP server: git-mcp

Installation

git clone https://github.com/LeonidYasin/mcp-server.git
cd mcp-server
pip install flask httpx python-dotenv flask-cors

Running

python -m mcp_server.server

The server starts on http://0.0.0.0:3001, MCP endpoint: POST /mcp.

The GitHub token is passed via the Authorization: Bearer <token> header.

Connecting to DeepSeek++

In the DeepSeek++ plugin settings:

  • URL: http://127.0.0.1:3001/mcp

  • Type: HTTP

  • Header: Authorization: Bearer <your_github_token>

Project structure

mcp-server/
├── pyproject.toml
├── README.md
└── mcp_server/
    ├── __init__.py
    ├── server.py              # Flask HTTP-сервер
    ├── core/
    │   ├── __init__.py
    │   ├── tool.py            # Tool dataclass
    │   └── registry.py        # ToolRegistry с авто-обнаружением
    └── tools/
        ├── __init__.py
        └── github/
            ├── __init__.py            # Экспорт инструментов
            ├── client.py              # GitHub API HTTP-клиент
            ├── file_ops.py            # get_file_contents, create_or_update_file, delete_file
            ├── file_sha_ops.py        # create_or_update_file_with_sha
            ├── create_update_binary.py # create_or_update_binary_file
            ├── commits.py             # list_commits, get_commit_status
            ├── workflows.py           # workflow-инструменты (4 шт)
            ├── workflow_runs.py       # list_workflow_runs, get_latest_run_id, get_workflow_run_steps, get_run_logs_by_step
            ├── build_logs.py          # watch_build
            ├── build_logs_loader.py   # auto_fix_build, get_android_build_error, get_ios_build_error
            └── build_logs_tools.py    # вспомогательные функции для сборки

How to add a new tool

Step 1: Create a file in mcp_server/tools/github/

Example: mcp_server/tools/github/create_branch.py

"""MCP tool: create_branch - создаёт новую ветку."""

from mcp_server.core.registry import mcp_tool
from mcp_server.tools.github.client import GitHubClient


@mcp_tool(
    name="create_branch",
    description="Создаёт новую ветку в репозитории",
    parameters={
        "owner": {"type": "string", "description": "Владелец репозитория"},
        "repo": {"type": "string", "description": "Имя репозитория"},
        "branch": {"type": "string", "description": "Имя новой ветки"},
        "from_branch": {"type": "string", "description": "Источник (по умолчанию main)"},
    },
    required=["owner", "repo", "branch"],
)
def create_branch(client: GitHubClient, owner: str, repo: str, branch: str, from_branch: str = "main") -> dict:
    """Создать новую ветку."""
    # 1. Получаем SHA родительской ветки
    ref_resp = client._request(
        "GET", f"/repos/{owner}/{repo}/git/ref/heads/{from_branch}"
    )
    sha = ref_resp.json()["object"]["sha"]

    # 2. Создаём ветку
    client._request(
        "POST",
        f"/repos/{owner}/{repo}/git/refs",
        json={"ref": f"refs/heads/{branch}", "sha": sha},
    )

    return {
        "content": [{
            "type": "text",
            "text": f"✅ Ветка '{branch}' создана из '{from_branch}'"
        }]
    }

Step 2: Export the tool

In mcp_server/tools/github/__init__.py, add the line:

from mcp_server.tools.github.create_branch import create_branch

Step 3: Restart the server

# Остановите Ctrl+C и снова запустите
python -m mcp_server.server

The tool will automatically appear in the list. No other configuration is required.

How auto-discovery works

ToolRegistry (in mcp_server/core/registry.py) on startup:

  1. Scans mcp_server/tools/

  2. Finds all subpackages (directories with __init__.py)

  3. Imports them and looks for functions decorated with @mcp_tool

  4. Registers the found tools

Rules for writing tools

  1. The function must be synchronous and take client: GitHubClient as the first argument

  2. The @mcp_tool decorator defines:

    • name — the tool name (how it will be called)

    • description — a description for the AI assistant

    • parameters — a dictionary of parameters in JSON Schema format

    • required — a list of required parameters

  3. Return a dict with the content key — a list of {"type": "text", "text": "..."} objects

  4. For GitHub API requests, use client._request(method, path, ...)

Template for copying

"""MCP tool: имя_инструмента - краткое описание."""

from mcp_server.core.registry import mcp_tool
from mcp_server.tools.github.client import GitHubClient


@mcp_tool(
    name="имя_инструмента",
    description="Что делает инструмент",
    parameters={
        "owner": {"type": "string", "description": "Владелец репозитория"},
        "repo": {"type": "string", "description": "Имя репозитория"},
    },
    required=["owner", "repo"],
)
def имя_инструмента(client: GitHubClient, owner: str, repo: str) -> dict:
    # Ваш код здесь
    return {
        "content": [{"type": "text", "text": "Результат работы"}]
    }

GitHub token requirements

The token must have the following permissions (scopes):

  • repo (or Contents: Read and write) — for working with files

  • Actions: Read — for viewing workflows

  • Metadata: Read — for basic information (usually enabled by default)

Testing the server via curl

# Проверка списка инструментов
curl -X POST http://127.0.0.1:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <токен>" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# Чтение файла
curl -X POST http://127.0.0.1:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <токен>" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"get_file_contents","arguments":{"owner":"LeonidYasin","repo":"mcp-server","path":"README.md"}}}'

Version history

  • v0.1.0 — stdio transport, basic modular architecture

  • v0.2.0 — Flask HTTP transport, 10 tools, auto-discovery, developer instructions

  • v0.3.0 — Added 9 new tools: 19 total, including workflow, build, and debugging support

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • git-mcp

    abhi-d-git
    F
    license
    Not graded
    quality
    D
    maintenance
    Standalone MCP server for GitHub that enables repository management, branch operations, pull request handling, and commit retrieval via tools listed in the README.
    1
    -

  • @cloud9-labs/mcp-github

    cloud9-labs
    A
    license
    B
    quality
    D
    maintenance
    MCP (Model Context Protocol) server for GitHub API integration. This server provides comprehensive tools for interacting with GitHub repositories, issues, pull requests, branches, and code search through a unified interface.
    15
    5 npm
    MIT

  • github-mcp-bridge

    SamNewhouse
    F
    license
    Not graded
    quality
    B
    maintenance
    A lightweight MCP server that exposes GitHub operations as tools over HTTP, enabling any MCP-compatible client to interact with GitHub repositories without a built-in connector.
    1
    -