GitHub MCP Agent Server

Python License

MCP (Model Context Protocol) server that exposes GitHub operations as tools for AI agents — Claude Code, Codex, and any MCP-compatible client.

Features

Tool	Description
`search_code`	Search GitHub repositories for code
`list_issues`	List open/closed issues in a repository
`create_issue`	Create a new GitHub issue
`get_pr_diff`	Fetch the raw diff of any pull request
`create_pr`	Create a pull request between branches
`review_pr_diff`	Automated code review via local rules (no API call)

Quick Start

1. Prerequisites

Python 3.10+
A GitHub personal access token with repo scope

2. Install

pip install fastmcp httpx python-dotenv

3. Configure

git clone https://github.com/FMorgan-111/github-mcp-server.git
cd github-mcp-server
echo "GITHUB_TOKEN=ghp_your_token_here" > .env

4. Run

python -m src.main

5. Connect to your AI agent

Claude Code:

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

Or via Claude Desktop / Cursor config:

{
  "mcpServers": {
    "github-agent": {
      "command": "python3",
      "args": ["/path/to/github-mcp-server/src/main.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Then ask your AI:

"List open issues in FMorgan-111/github-mcp-server""Search for 'FastMCP' in my repo""Review PR #1 in this repo"

Tool Reference

`search_code(query, repo)`

Search code within a GitHub repository.

Parameters:

query (str, required) — Search query
repo (str, optional) — Repository in owner/repo format

Returns: Formatted list of matching files with paths and URLs.

`list_issues(repo, state)`

List issues in a repository.

Parameters:

repo (str, required) — Repository in owner/repo format
state (str, optional) — "open" (default) or "closed"

`create_issue(repo, title, body)`

Create a new issue.

Parameters:

repo (str, required) — Repository in owner/repo format
title (str, required) — Issue title
body (str, required) — Issue body text

`get_pr_diff(repo, pr_number)`

Fetch the raw diff of a pull request.

Parameters:

repo (str, required) — Repository in owner/repo format
pr_number (int, required) — Pull request number

`create_pr(repo, title, body, head, base)`

Create a pull request.

Parameters:

repo (str, required) — Repository in owner/repo format
title (str, required) — PR title
body (str, required) — PR description
head (str, required) — Source branch name
base (str, required) — Target branch name (e.g. "main")

`review_pr_diff(repo, pr_number)`

Fetch a PR diff and run local code review rules. No API call — all analysis is local.

Rules checked:

⚠️ print() statements in non-test files
⚠️ TODO / FIXME / HACK comments
❌ Hardcoded secrets (passwords, API keys, tokens)
❌ Bare except: clauses (should specify exception type)
⚠️ Functions over 80 lines

Architecture

┌─────────────────┐     MCP stdio transport     ┌──────────────────────┐
│  Claude Code    │ ◄─────────────────────────► │  GitHub MCP Server   │
│  Codex          │     JSON-RPC 2.0 messages    │                      │
│  Any MCP client │                              │  ┌────────────────┐ │
└─────────────────┘                              │  │  github_client │ │
                                                 │  │  (httpx)       │ │
                                                 │  │  → GitHub API  │ │
                                                 │  └────────────────┘ │
                                                 │  ┌────────────────┐ │
                                                 │  │  review.py     │ │
                                                 │  │  local rules   │ │
                                                 │  └────────────────┘ │
                                                 │  ┌────────────────┐ │
                                                 │  │  config.py     │ │
                                                 │  │  .env / env    │ │
                                                 │  └────────────────┘ │
                                                 └──────────────────────┘

Development

# Clone and install
git clone https://github.com/FMorgan-111/github-mcp-server.git
cd github-mcp-server
pip install -e . --break-system-packages

# Run tests
python -m pytest tests/ -v

# Start MCP server (stdio mode)
python -m src.main

# Test with MCP Inspector
# https://github.com/modelcontextprotocol/inspector

Deployment

Docker

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

Smithery (MCP Registry)

Deploy to Smithery for one-click install into any MCP client.

License

MIT

GitHub MCP Agent Server