ouranos/docs/github_mcp.md

GitHub MCP Server

Overview

The GitHub MCP server provides read-only access to GitHub repositories through the Model Context Protocol (MCP). It enables AI assistants and other MCP clients to explore repository contents, search code, read issues, and analyze pull requests without requiring local clones.

Deployment Host: miranda.incus (10.10.0.156)
Port: 25533 (HTTP MCP endpoint)
MCPO Proxy: http://miranda.incus:25530/github

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MCP CLIENTS                               │
│  VS Code/Cline │ OpenWebUI │ Custom Applications            │
└─────────────────────────┬───────────────────────────────────┘
                          │
              ┌───────────┴──────────────┐
              │                          │
              ▼                          ▼
   Direct MCP (port 25533)    MCPO Proxy (port 25530)
   streamable-http             OpenAI-compatible API
              │                          │
              └──────────┬───────────────┘
                         ▼
              ┌──────────────────────┐
              │  GitHub MCP Server   │
              │  Docker Container    │
              │  miranda.incus       │
              └──────────┬───────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │    GitHub API        │
              │  (Read-Only PAT)     │
              └──────────────────────┘

---

GitHub Personal Access Token

Required Scopes

The GitHub MCP server requires a read-only Personal Access Token (PAT) with the following scopes:

Scope	Purpose
public_repo	Read access to public repositories
repo	Read access to private repositories (if needed)
read:org	Read organization membership and teams
read:user	Read user profile information

Creating a PAT

1. Navigate to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Set name: Agathos GitHub MCP - Read Only
4. Set expiration: Custom or 90 days (recommended)
5. Select scopes: public_repo, read:org, read:user
6. Click "Generate token"
7. Copy the token immediately (it won't be shown again)
8. Store in Ansible vault: ansible-vault edit ansible/inventory/group_vars/all/vault.yml
   • Add: vault_github_personal_access_token: "ghp_xxxxxxxxxxxxx"

---

Available Tools

The GitHub MCP server provides the following tools:

Repository Operations

• get_file_contents - Read file contents from repository
• search_repositories - Search for repositories on GitHub
• list_commits - List commits in a repository
• create_branch - Create a new branch (requires write access)
• push_files - Push files to repository (requires write access)

Issue Management

• create_issue - Create a new issue (requires write access)
• list_issues - List issues in a repository
• get_issue - Get details of a specific issue
• update_issue - Update an issue (requires write access)

Pull Request Management

• create_pull_request - Create a new PR (requires write access)
• list_pull_requests - List pull requests in a repository
• get_pull_request - Get details of a specific PR

Search Operations

• search_code - Search code across repositories
• search_users - Search for GitHub users

Note: With a read-only PAT, write operations (create_*, update_*, push_*) will fail. The primary use case is repository exploration and code reading.

---

Client Configuration

MCP Native Clients (Cline, Claude Desktop)

Add the following to your MCP settings (e.g., ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "github": {
      "type": "streamable-http",
      "url": "http://miranda.incus:25533/mcp"
    }
  }
}

OpenWebUI Configuration

1. Navigate to Settings → Tools → OpenAPI Servers
2. Click Add OpenAPI Server
3. Configure:
   • Name: GitHub MCP
   • URL: http://miranda.incus:25530/github
   • Authentication: None (MCPO handles upstream auth)
4. Save and enable desired GitHub tools

Custom Applications

Direct MCP Connection:

import mcp

client = mcp.Client("http://miranda.incus:25533/mcp")
tools = await client.list_tools()

Via MCPO (OpenAI-compatible):

import openai

client = openai.OpenAI(
    base_url="http://miranda.incus:25530/github",
    api_key="not-required"  # MCPO doesn't require auth for GitHub MCP
)

---

Deployment

Prerequisites

• Miranda container running with Docker installed
• Ansible vault containing vault_github_personal_access_token
• Network connectivity from clients to miranda.incus

Deploy GitHub MCP Server

cd /home/robert/dv/agathos/ansible
ansible-playbook github_mcp/deploy.yml

This playbook:

1. Creates github_mcp user and group
2. Creates /srv/github_mcp directory
3. Templates docker-compose.yml with PAT from vault
4. Starts github-mcp-server container on port 25533

Update MCPO Configuration

ansible-playbook mcpo/deploy.yml

This restarts MCPO with the updated config including GitHub MCP server.

Update Alloy Logging

ansible-playbook alloy/deploy.yml --limit miranda.incus

This reconfigures Alloy to collect GitHub MCP server logs.

---

Verification

Test Direct MCP Endpoint

# Check container is running
ssh miranda.incus docker ps | grep github-mcp-server

# Test MCP endpoint responds
curl http://miranda.incus:25533/mcp

# List available tools (expect JSON response)
curl -X POST http://miranda.incus:25533/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Test MCPO Proxy

# List GitHub tools via MCPO
curl http://miranda.incus:25530/github/tools

# Test repository file reading
curl -X POST http://miranda.incus:25530/github/tools/get_file_contents \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "github",
    "repo": "docs",
    "path": "README.md"
  }'

View Logs

# Container logs
ssh miranda.incus docker logs github-mcp-server

# Loki logs (via Grafana on prospero.incus)
# Navigate to Explore → Loki
# Query: {job="github-mcp-server"}

---

Troubleshooting

Container Won't Start

Check Docker Compose:

ssh miranda.incus
sudo -u github_mcp docker compose -f /srv/github_mcp/docker-compose.yml logs

Common Issues:

• Missing or invalid GitHub PAT in vault
• Port 25533 already in use
• Docker image pull failure

MCP Endpoint Returns Errors

Check GitHub PAT validity:

curl -H "Authorization: token YOUR_PAT" https://api.github.com/user

Verify PAT scopes:

curl -i -H "Authorization: token YOUR_PAT" https://api.github.com/user \
  | grep X-OAuth-Scopes

MCPO Not Exposing GitHub Tools

Verify MCPO config:

ssh miranda.incus cat /srv/mcpo/config.json | jq '.mcpServers.github'

Restart MCPO:

ssh miranda.incus sudo systemctl restart mcpo
ssh miranda.incus sudo systemctl status mcpo

---

Monitoring

Prometheus Metrics

GitHub MCP server exposes Prometheus metrics (if supported by the container). Add to Prometheus scrape config:

scrape_configs:
  - job_name: 'github-mcp'
    static_configs:
      - targets: ['miranda.incus:25533']

Grafana Dashboard

Import or create a dashboard on prospero.incus to visualize:

• Request rate and latency
• GitHub API rate limits
• Tool invocation counts
• Error rates

Log Queries

Useful Loki queries in Grafana:

# All GitHub MCP logs
{job="github-mcp-server"}

# Errors only
{job="github-mcp-server"} |= "error" or |= "ERROR"

# GitHub API rate limit warnings
{job="github-mcp-server"} |= "rate limit"

# Tool invocations
{job="github-mcp-server"} |= "tool"

---

Security Considerations

✔ Read-Only PAT - Server uses minimal scopes, cannot modify repositories
✔ Network Isolation - Only accessible within Agathos network (miranda.incus)
✔ Vault Storage - PAT stored encrypted in Ansible Vault
✔ No Public Exposure - MCP endpoint not exposed to internet
⚠️ PAT Rotation - Consider rotating PAT every 90 days
⚠️ Access Control - MCPO currently doesn't require authentication

Recommended Enhancements

1. Add authentication to MCPO endpoints
2. Implement request rate limiting
3. Monitor GitHub API quota usage
4. Set up PAT expiration alerts
5. Restrict network access to miranda via firewall rules

---

References

• GitHub MCP Server Repository
• Model Context Protocol Specification
• MCPO Documentation
• Agathos README
• Agathos Sandbox Documentation