MCP server giving AI agents controlled GitHub access with policy guard and audit trail.
┌───────────────┐ 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) │ │
└──────────────────────────────────────────────┘ │
└───┘
| 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 |
get_file_contents |
Read a file from a repository | get_file_contents("owner/repo", "src/main.py", ref="main") |
Decoded file content with metadata |
create_or_update_file |
Create or update a single file (guarded) | create_or_update_file("owner/repo", "src/app.py", content="print(1)", message="Add app.py") |
Commit SHA and URL |
push_files |
Push multiple files as a single commit | push_files("owner/repo", "main", "feat: add modules", '[{"path":"a.py","content":"..."}]') |
Commit SHA and file list |
add_issue_comment |
Comment on an issue or pull request | add_issue_comment("owner/repo", 1, "Looks good!") |
Comment URL |
merge_pull_request |
Merge a pull request | merge_pull_request("owner/repo", 42, merge_method="squash") |
Merge status and SHA |
- 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.jsonto configure repository allowlists and protected branches.
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.
- Python 3.10+
- GitHub personal access token with
reposcope
pip install fastmcp httpx python-dotenvgit clone https://github.com/FMorgan-111/github-mcp-server.git
cd github-mcp-server
cp .env.example .env && nano .env
python3 -m src.mainclaude mcp add github-agent -- python3 /path/to/github-mcp-server/src/main.pypip install -e . --break-system-packages
python3 -m pytest tests/ -v
python3 -m src.main106 tests, all passing.
docker build -t github-mcp-server .
docker run \
-e GITHUB_TOKEN=ghp_your_token_here \
-i github-mcp-serverThe -e GITHUB_TOKEN=... flag passes the token into the container because
the local .env file is not copied into the image.
MIT
