MCP GitHub Automation Server
README.md
# 🤖 MCP GitHub Automation Server
<p align="center">
<img src="https://capsule-render.vercel.app/api?type=venom&height=260&text=MCP%20GitHub%20Automation&fontSize=42&fontColor=ffffff&color=0:0f172a,50:1e3a8a,100:4f46e5&stroke=6366f1&strokeWidth=2&animation=twinkling&fontAlignY=45" width="100%"/>
</p>
<p align="center">
<strong>AI-Powered GitHub Automation using Model Context Protocol</strong>
</p>
<p align="center">
<a href="#">
<img src="https://img.shields.io/badge/Model%20Context%20Protocol-MCP-6366F1?style=for-the-badge&logo=probot&logoColor=white"/>
</a>
<a href="#">
<img src="https://img.shields.io/badge/Python-3.12-3776AB?style=for-the-badge&logo=python&logoColor=white"/>
</a>
<a href="#">
<img src="https://img.shields.io/badge/Docker-Containerized-2496ED?style=for-the-badge&logo=docker&logoColor=white"/>
</a>
<a href="#">
<img src="https://img.shields.io/badge/AWS-EC2-FF9900?style=for-the-badge&logo=amazonaws&logoColor=white"/>
</a>
</p>
<p align="center">
<a href="#">
<img src="https://img.shields.io/badge/GitHub-Automation-181717?style=for-the-badge&logo=github&logoColor=white"/>
</a>
<a href="#">
<img src="https://img.shields.io/badge/GitHub%20Actions-CI%2FCD-2088FF?style=for-the-badge&logo=githubactions&logoColor=white"/>
</a>
<a href="#">
<img src="https://img.shields.io/badge/GHCR-Container%20Registry-181717?style=for-the-badge&logo=github&logoColor=white"/>
</a>
<a href="#">
<img src="https://img.shields.io/badge/Linux-Ubuntu-E95420?style=for-the-badge&logo=ubuntu&logoColor=white"/>
</a>
</p>
---
## 📌 Project Overview
This project demonstrates how to build, containerize, deploy, and automatically update a **Model Context Protocol (MCP) server** for GitHub automation.
The MCP server is developed using **Python** and exposes GitHub-related tools that can be discovered and invoked by an MCP-compatible AI application.
The complete application is:
```text
Python MCP Server
↓
GitHub REST API
↓
Docker Container
↓
GitHub Container Registry
↓
AWS EC2
↓
GitHub Actions CI/CD
````
---
## 🎯 Project Objectives
* 🧠 Understand Model Context Protocol
* 🔌 Build a custom MCP server
* 🛠️ Implement MCP tools
* 🐙 Integrate GitHub REST API
* 🐳 Containerize the MCP server
* ☁️ Deploy the server on AWS EC2
* 📦 Publish Docker images to GHCR
* ⚙️ Implement GitHub Actions CI/CD
* 🔐 Secure API credentials
* 🚀 Automate application deployment
---
# 🧠 What is MCP?
**Model Context Protocol (MCP)** is a standardized protocol that allows AI applications to interact with external tools, resources, and services.
Instead of creating a separate integration for every AI application and external system, MCP provides a common interface.
```text
┌─────────────────────┐
│ AI Application │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ MCP Client │
└──────────┬──────────┘
│
MCP Protocol
│
▼
┌─────────────────────┐
│ MCP Server │
└──────────┬──────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
🛠 Tools 📚 Resources 💬 Prompts
│ │ │
└──────────────────┼──────────────────┘
│
▼
External Systems
```
---
# 🔌 MCP Architecture
```text
┌──────────────────────────────────────────────────────────────┐
│ AI APPLICATION │
│ │
│ ChatGPT / Claude / Other MCP-Compatible AI Application │
└────────────────────────────┬─────────────────────────────────┘
│
▼
┌─────────────────┐
│ MCP Client │
└────────┬────────┘
│
│ MCP
▼
┌──────────────────────────────────────────────────────────────┐
│ AWS EC2 │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Docker Container │ │
│ │ │ │
│ │ Python MCP Server │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │
│ │ │ Repository │ │ Issues │ │ Workflows │ │ │
│ │ │ Tool │ │ Tool │ │ Tool │ │ │
│ │ └──────┬─────┘ └─────┬──────┘ └──────┬───────┘ │ │
│ └──────────┼──────────────┼───────────────┼───────────┘ │
└──────────────┼──────────────┼───────────────┼───────────────┘
│ │ │
└──────────────┼───────────────┘
▼
┌──────────────────┐
│ GitHub REST API │
└────────┬─────────┘
│
▼
🐙 GitHub
```
---
# 🐙 GitHub Automation Use Case
GitHub was selected as the practical MCP use case.
The MCP server provides controlled access to GitHub information through reusable tools.
### Problem
AI applications need a standardized and secure way to interact with GitHub repositories, issues, and workflows.
### MCP Solution
The MCP server acts as a controlled gateway between the AI application and GitHub.
```text
AI
│
▼
MCP Client
│
▼
MCP Server
│
├── Repository Information
├── Issue Management
└── Workflow Monitoring
│
▼
GitHub API
```
---
# 🛠️ MCP Tools
| Tool | Purpose |
| ----------------------- | ------------------------------------ |
| `get_repository_info()` | Retrieve repository information |
| `list_issues()` | Retrieve open GitHub issues |
| `get_workflow_status()` | Check GitHub Actions workflow status |
---
## 📦 Repository Information
```text
get_repository_info()
```
Returns:
```text
Repository Name
Description
Visibility
Default Branch
Stars
Forks
```
---
## 🐛 Issue Management
```text
list_issues()
```
Returns open GitHub issues.
Example:
```text
Issue #12
Title: Docker deployment issue
State: OPEN
```
---
## ⚙️ Workflow Monitoring
```text
get_workflow_status()
```
Returns GitHub Actions workflow information.
Example:
```text
Workflow: MCP Server CI/CD
Status: completed
Conclusion: success
Branch: main
```
---
# 🧰 Technology Stack
<p align="center">
<img src="https://skillicons.dev/icons?i=python,docker,aws,ubuntu,github,git,githubactions&perline=7" />
</p>
| Category | Technology |
| ------------ | ------------------------- |
| 🤖 Protocol | Model Context Protocol |
| 🐍 Language | Python 3.12 |
| 🔌 SDK | MCP Python SDK |
| 🐙 API | GitHub REST API |
| 🌐 HTTP | HTTPX |
| 🐳 Container | Docker |
| 📦 Registry | GitHub Container Registry |
| ☁️ Cloud | AWS |
| 💻 Compute | EC2 |
| 🐧 OS | Ubuntu |
| ⚙️ CI/CD | GitHub Actions |
| 🔬 Testing | MCP Inspector |
| 🌐 Transport | Streamable HTTP |
---
# 📁 Project Structure
```text
github-mcp-server/
│
├── 📄 server.py
├── 📄 requirements.txt
├── 🐳 Dockerfile
├── 📄 .dockerignore
├── 📄 .gitignore
├── 📄 README.md
│
└── .github/
└── workflows/
└── 🚀 deploy.yml
```
---
# ⚙️ Environment Configuration
Create a `.env` file:
```env
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository_name
```
### 🔐 Never commit `.env`
Add the following to `.gitignore`:
```gitignore
.env
venv/
__pycache__/
*.pyc
```
---
# 💻 Local Development
## Clone Repository
```bash
git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
```
```bash
cd github-mcp-server
```
## Create Virtual Environment
```bash
python -m venv venv
```
Linux:
```bash
source venv/bin/activate
```
Windows:
```powershell
venv\Scripts\activate
```
## Install Dependencies
```bash
pip install -r requirements.txt
```
## Start Server
```bash
python server.py
```
---
# 🌐 MCP Endpoint
The MCP server uses **Streamable HTTP**.
Local:
```text
http://localhost:8000/mcp
```
AWS EC2:
```text
http://EC2_PUBLIC_IP:8000/mcp
```
For production:
```text
https://mcp.example.com/mcp
```
---
# 🐳 Docker
## Build Image
```bash
docker build -t github-mcp-server .
```
## Run Container
```bash
docker run -d \
--name mcp-server \
--env-file .env \
-p 8000:8000 \
github-mcp-server
```
## Verify
```bash
docker ps
```
## View Logs
```bash
docker logs mcp-server
```
---
# 🐳 Dockerfile
```dockerfile
FROM python:3.12-slim
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server.py .
EXPOSE 8000
CMD ["python", "server.py"]
```
---
# ☁️ AWS EC2 Deployment
The MCP server is deployed on an Ubuntu EC2 instance using Docker.
## Install Docker
```bash
sudo apt update
sudo apt install -y docker.io
```
Enable Docker:
```bash
sudo systemctl enable docker
sudo systemctl start docker
```
Verify:
```bash
docker --version
```
---
## Clone Project
```bash
git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
```
```bash
cd github-mcp-server
```
---
## Configure Environment
```bash
nano .env
```
Add:
```env
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository_name
```
Secure the file:
```bash
chmod 600 .env
```
---
## Run MCP Server
```bash
docker build -t github-mcp-server .
```
```bash
docker run -d \
--name mcp-server \
--restart unless-stopped \
--env-file .env \
-p 8000:8000 \
github-mcp-server
```
Verify:
```bash
docker ps
```
---
# 🔄 CI/CD Pipeline
<p align="center">
<img src="https://capsule-render.vercel.app/api?type=rect&color=0:111827,100:2563EB&height=100§ion=header&text=Automated%20CI%2FCD%20Pipeline&fontSize=30&fontColor=FFFFFF" width="100%"/>
</p>
```text
👨💻 Developer
│
│ git push
▼
🐙 GitHub Repository
│
▼
⚙️ GitHub Actions
│
┌─────────┴─────────┐
│ │
▼ ▼
🧪 Test 🐳 Build
│ │
└─────────┬─────────┘
│
▼
📦 Docker Image
│
▼
📦 GHCR
│
▼
🔐 SSH Deploy
│
▼
☁️ AWS EC2
│
▼
🐳 Docker
│
▼
🤖 MCP Server
```
---
# ⚙️ GitHub Actions
The pipeline automatically executes when code is pushed to the `main` branch.
### Pipeline Stages
```text
Checkout
↓
Setup Python
↓
Install Dependencies
↓
Run Tests
↓
Build Docker Image
↓
Login to GHCR
↓
Push Docker Image
↓
Connect to EC2
↓
Pull Latest Image
↓
Stop Old Container
↓
Start New Container
```
---
# 🔐 GitHub Secrets
Configure secrets under:
```text
Repository
↓
Settings
↓
Secrets and variables
↓
Actions
```
Required:
```text
EC2_HOST
EC2_USERNAME
EC2_SSH_KEY
GHCR_USERNAME
GHCR_TOKEN
```
Secrets must never be committed to GitHub.
---
# 📦 GitHub Container Registry
Images are stored in GHCR.
Example:
```text
ghcr.io/YOUR_USERNAME/github-mcp-server:latest
```
Commit-based image:
```text
ghcr.io/YOUR_USERNAME/github-mcp-server:<commit-sha>
```
This provides versioned and reproducible container deployments.
---
# 🧪 Testing
## Python Syntax Test
```bash
python -m py_compile server.py
```
## Docker Build Test
```bash
docker build -t github-mcp-server .
```
## Container Test
```bash
docker ps
```
## Log Verification
```bash
docker logs mcp-server
```
---
# 🔎 MCP Tool Verification
Connect an MCP-compatible client or MCP Inspector to:
```text
http://localhost:8000/mcp
```
Verify tool discovery:
```text
✓ get_repository_info
✓ list_issues
✓ get_workflow_status
```
---
# 🔐 Security
Security is critical because MCP servers can provide AI applications with access to external systems.
### 🔑 Secret Management
Never hard-code:
```text
GitHub Tokens
AWS Credentials
SSH Keys
API Keys
Passwords
```
Use:
```text
GitHub Secrets
Environment Variables
AWS Secrets Manager
```
---
### 🛡️ Least Privilege
GitHub tokens should only receive the permissions required by the MCP tools.
Prefer read-only permissions when write operations are not required.
---
### 🚫 Avoid Dangerous Tools
Avoid unrestricted operations such as:
```text
delete_repository()
delete_branch()
merge_pull_request()
create_deployment()
```
unless proper authorization and confirmation are implemented.
---
### 🌐 Network Security
Restrict EC2 access.
Recommended:
```text
SSH
Port 22
Source: Your IP/32
```
For production MCP access:
```text
HTTPS
Port 443
Source: Authorized Clients
```
---
### 🧠 Prompt Injection Protection
GitHub issues, comments, pull requests, and repository content may contain untrusted instructions.
External content should be treated as **data**, not automatically as trusted instructions.
---
# 📊 Deployment Verification
After making changes:
```bash
git add .
```
```bash
git commit -m "Update MCP server"
```
```bash
git push origin main
```
GitHub Actions:
```text
🧪 Test → ✅ Passed
🐳 Docker Build → ✅ Passed
📦 GHCR Push → ✅ Passed
☁️ EC2 Deploy → ✅ Passed
```
EC2:
```bash
docker ps
```
Logs:
```bash
docker logs mcp-server
```
---
# 🔁 End-to-End Workflow
```text
┌─────────────────┐
│ Developer │
└────────┬────────┘
│
git push
│
▼
┌─────────────────┐
│ GitHub │
└────────┬────────┘
│
▼
┌─────────────────┐
│ GitHub Actions │
└────────┬────────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
🧪 Test 🐳 Build
│ │
└─────────┬─────────┘
│
▼
┌─────────────────┐
│ GHCR │
└────────┬────────┘
│
▼
┌─────────────────┐
│ AWS EC2 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Docker Container│
└────────┬────────┘
│
▼
┌─────────────────┐
│ MCP Server │
└────────┬────────┘
│
▼
┌─────────────────┐
│ GitHub API │
└─────────────────┘
```
---
# 📚 MCP Concepts Covered
| Concept | Description |
| --------------- | --------------------------------------- |
| MCP Client | Connects AI applications to MCP servers |
| MCP Server | Exposes capabilities to MCP clients |
| Tools | Executable functions |
| Resources | Data/context exposed to clients |
| Prompts | Reusable interaction templates |
| Transport | Communication mechanism |
| Tool Discovery | Client discovers available tools |
| Tool Invocation | Client calls a selected tool |
---
# 🚀 Key DevOps Practices
```text
SOURCE CONTROL
│
▼
GIT
│
▼
CI/CD PIPELINE
│
▼
AUTOMATED TEST
│
▼
DOCKER BUILD
│
▼
CONTAINER REGISTRY
│
▼
CLOUD DEPLOYMENT
│
▼
RUNTIME SECRETS
│
▼
SECURITY
```
---
# ✨ Project Highlights
* 🤖 Custom MCP server built with Python
* 🐙 GitHub REST API integration
* 🛠️ Three reusable MCP tools
* 🌐 Streamable HTTP transport
* 🐳 Docker containerization
* 📦 GitHub Container Registry
* ☁️ AWS EC2 deployment
* ⚙️ GitHub Actions CI/CD
* 🔐 Secure secret management
* 🛡️ Least-privilege access
* 🔄 Automated deployment
* 🧪 Automated validation
* 📊 GitHub workflow monitoring
---
# 🔮 Future Enhancements
```text
HTTPS
↓
Custom Domain
↓
AWS ALB
↓
AWS Secrets Manager
↓
Amazon ECR
↓
Amazon ECS
↓
Kubernetes
↓
Terraform
↓
Prometheus
↓
Grafana
```
Potential MCP improvements:
* 🔍 Repository search
* 🔀 Pull request management
* 📝 Create GitHub issues
* 💬 Pull request comments
* 🏷️ GitHub label management
* 🔐 Authentication and authorization
* 🚦 Rate limiting
* 📊 Monitoring and observability
* 🛡️ Container vulnerability scanning
---
# 🏆 Skills Demonstrated
<p align="center">
<img src="https://skillicons.dev/icons?i=python,docker,aws,linux,github,git,githubactions,terraform,kubernetes&perline=9" />
</p>
```text
Model Context Protocol
Python
GitHub REST API
Docker
AWS EC2
GitHub Actions
GHCR
Linux
Git
CI/CD
REST APIs
Cloud Security
Containerization
Automation
```
---
# 📈 Learning Outcomes
By completing this project, the following concepts were implemented and understood:
* Model Context Protocol
* MCP Client and Server architecture
* MCP Tools
* MCP Resources
* MCP Prompts
* Tool discovery
* Tool invocation
* GitHub API integration
* Python MCP development
* Streamable HTTP
* Docker containerization
* GHCR
* AWS EC2
* GitHub Actions
* CI/CD automation
* Secret management
* Cloud security
* Automated deployment
---
# 💼 Resume Project Description
> **MCP GitHub Automation Server | Python, MCP, Docker, AWS EC2, GitHub Actions**
>
> Developed and deployed a Python-based Model Context Protocol server for GitHub automation, exposing tools for repository information, issue retrieval, and GitHub Actions workflow monitoring. Containerized the application using Docker, published images to GitHub Container Registry, deployed on AWS EC2, and implemented GitHub Actions CI/CD for automated testing, image publishing, and remote deployment. Applied secure credential management, least-privilege access, and cloud network security practices.
---
# 👨💻 Author
## Venu Gopala Reddy Eppala
**Cloud & DevOps Engineer**
<p align="left">
<img src="https://img.shields.io/badge/AWS-Cloud-FF9900?style=flat-square&logo=amazonaws&logoColor=white"/>
<img src="https://img.shields.io/badge/Docker-Containers-2496ED?style=flat-square&logo=docker&logoColor=white"/>
<img src="https://img.shields.io/badge/Kubernetes-Orchestration-326CE5?style=flat-square&logo=kubernetes&logoColor=white"/>
<img src="https://img.shields.io/badge/Terraform-IaC-7B42BC?style=flat-square&logo=terraform&logoColor=white"/>
<img src="https://img.shields.io/badge/CI%2FCD-Automation-2088FF?style=flat-square&logo=githubactions&logoColor=white"/>
</p>
---
<p align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:4F46E5,50:1E3A8A,100:0F172A&height=120§ion=footer" width="100%"/>
</p>
<p align="center">
<strong>Built with MCP • Docker • AWS • GitHub Actions</strong>
</p>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues