mcp-github-agent 0.1.0

MCP server giving AI agents controlled GitHub access with policy guard and audit trail

GitHub MCP Agent Server

MCP server giving AI agents controlled GitHub access with policy guard and audit trail.

---

Architecture

   ┌───────────────┐        MCP stdio         ┌───────────────────┐
   │   AI Agent    │ ◄──────────────────────► │ GitHub MCP Server │
   │ (Claude, Codex│      JSON-RPC 2.0        │                   │
   │   or any MCP  │                         ┌─┴───────────────┐   │
   │    client)    │                         │ Policy Guard    │   │
   └───────────────┘                         ├─────────────────┤   │
                                             │ Audit Log       │   │
                                             └─────────────────┘   │
           ┌──────────────────────────────────────────────┐      │
           │                 github_client.py               │      │
           │                    (httpx)                     │      │
           │                   GitHub API                   │      │
           └──────────────────────────────────────────────┘      │
           ┌──────────────────────────────────────────────┐      │
           │          Review Engine (ruff + regex)          │      │
           └──────────────────────────────────────────────┘      │
                                                                └───┘

---

Features & Tools

Tool	Description	Example Input	Example Output
search_code	Search GitHub repo code by query	search_code("def main", "owner/repo")	List of matching files with paths & URLs
list_issues	List open or closed issues	list_issues("owner/repo", state="open")	Formatted list of issues
create_issue	Create a new issue (policy-guarded)	create_issue("owner/repo", "Bug: timeout", "Steps to reproduce...")	Confirmation with issue URL
get_pr_diff	Fetch raw diff of a pull request	get_pr_diff("owner/repo", pr_number=7)	Unified diff as text
create_pr	Create a pull request between branches	create_pr("owner/repo", "Add feature", "Details...", head="feat", base="main")	Confirmation with PR URL
review_pr_diff	Run local automated code review rules	review_pr_diff("owner/repo", pr_number=7)	List of warnings and errors found
comment_pr_review	Post review findings as PR comments	comment_pr_review("owner/repo", pr_number=7)	Number of comments posted

---

Security Model

• Repository Allowlist: Only repositories explicitly allowed by policy can be accessed.
• Branch Protection: PRs to protected branches are subject to branch protection rules before merging.
• Dry-Run Mode: Execute operations without side effects for safe testing and auditing.
• Audit Logging: All actions logged in JSONL format with precise timestamps to maintain traceability.
• Policy Configuration: Start from policy.example.json to configure repository allowlists and protected branches.

---

FAQ

Why not call the GitHub API directly?
Direct API calls lack centralized policy enforcement, audit logging, and uniform tooling support for AI agents. This MCP server adds a controlled, auditable layer for safer automation.

What MCP clients work with this?
Agents like Claude Code, OpenAI Codex, and any client supporting the MCP JSON-RPC 2.0 transport can connect to this server.

How is this different from the official GitHub MCP server?
This project's key differentiator is policy enforcement. Repository allowlists prevent agents from touching unauthorized repos, branch protection blocks accidental PRs to sensitive branches, dry-run mode supports safe validation, and write actions are audit-logged with timestamps.

---

Quick Start

Prerequisites

• Python 3.10+
• GitHub personal access token with repo scope

Install

pip install fastmcp httpx python-dotenv

Configure and Run

git clone https://github.com/FMorgan-111/github-mcp-server.git
cd github-mcp-server
cp .env.example .env && nano .env
python3 -m src.main

Connect with Claude Code

claude mcp add github-agent -- python3 /path/to/github-mcp-server/src/main.py

---

Development

pip install -e . --break-system-packages
python3 -m pytest tests/ -v
python3 -m src.main

23 tests, all passing.

---

Deployment with Docker

docker build -t github-mcp-server .
docker run -e GITHUB_TOKEN=ghp_your_token_here -i github-mcp-server

The -e GITHUB_TOKEN=... flag passes the token into the container because the local .env file is not copied into the image.

---

License

MIT