GitHub Project Management MCP Server

Custom MCP (Model Context Protocol) server that enables AI assistants to programmatically manage GitHub Project V2 boards via the Model Context Protocol. Built with Python 3.12 and FastMCP, communicates over stdio transport, and runs inside a standalone Docker container.

Location

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

Note: This MCP server is a standalone component with its own Dockerfile, dependencies, and lifecycle.

Related MCP server: my_pm_tools

How It Works

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

1. El cliente MCP invoca una herramienta (ej: create_project_item)

2. Se ejecuta docker run --rm -i github-project-mcp:latest python server.py

3. El servidor valida autenticación y espera comandos por stdin

4. El cliente envía JSON-RPC via stdin, recibe respuestas por stdout

5. Al finalizar, el contenedor se destruye automáticamente (--rm)

Docker — Construir y Gestionar

Construir la imagen

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose (desarrollo local)

La forma más simple de configurar y correr el MCP localmente:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefile Targets

Todos los targets ejecutan dentro de Docker — sin dependencias del host.

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

Nota: Si make no está disponible en el host, los targets pueden invocarse directamente con Docker. Ejemplo: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

Cada contributor clona el repo, crea su .env, y el MCP funciona sin instalar nada más que Docker.

Verificar que la imagen existe

docker images | grep github-project-mcp

Probar manualmente (smoke test)

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

El servidor imprimirá en stderr: github-project-management MCP server ready. Authentication validated successfully. Luego espera JSON-RPC por stdin. Presiona Ctrl+C para salir.

Reconstruir después de cambios

docker build -t github-project-mcp:latest ./mcp --no-cache

Script de gestión

El script ./scripts/dev/start.sh soporta un argumento mcp para gestionar la imagen:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

Nota: El MCP no es un servicio persistente. No necesita up/down/restart. Se lanza bajo demanda cada vez que el cliente usa una herramienta.

IDE Integration

El MCP es compatible con cualquier cliente que soporte el protocolo MCP sobre stdio. La configuración varía por IDE — el patrón general es:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

Para configuración específica por IDE, ver docs/SETUP.md.

Registered Tools (100)

Core Operations

Issue Management

Board Operations

Planning & Workflows

Metadata

Architecture

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

Delegation Strategy

Environment Variables

Troubleshooting

MCP no conecta

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

Reconectar MCP

Si el MCP se desconecta del IDE, usar la opción de reconexión del cliente MCP correspondiente.

Error de autenticación

• Verificar que GITHUB_TOKEN está disponible en el entorno del contenedor

• Tokens github_pat_* (fine-grained) necesitan permisos: Issues (RW), Projects (RW), Metadata (R)

• Tokens clásicos necesitan scopes: repo, project, read:org

Related Documentation

Source locations and synchronization

This directory (mcp/) is the canonical source of truth for the MCP package.

The repository contains a synchronized copy at:

• app/backend/app/mcp/github_project/ — embedded in the backend for Docker builds

Sync workflow

1. Make all changes here in mcp/ first.

2. Copy modified files to the embedded path:

   cp mcp/<file> app/backend/app/mcp/github_project/<file>

3. Verify with the automated check:

   ./mcp/scripts/check_sync.sh

The sync script compares all shared .py files (excluding __init__.py which is intentionally different in the backend copy, and infra-only files like Dockerfile and requirements.txt). CI runs this check on every push — divergence fails the build.

Files intentionally different in the backend copy

The backend test suite exercises the embedded copy; syntax validation must compile both trees.

Hardened runtime behavior

All settings use the GH_PROJECT_ prefix and are validated at startup:

The metadata cache is written atomically, uses owner-only permissions (0600), rejects future timestamps, and is not reused when organization or project number differs. CLI and GraphQL diagnostics redact token-like values and are bounded before returning to the MCP client.

Docker-only validation

Run validation without host Python tooling:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

Local Validation (Pre-Push)

Always run before creating a PR or pushing changes. This mirrors the CI pipeline locally and catches issues before they reach GitHub Actions.

Quick Start

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

What It Checks

Available Scripts

Common Issues and Fixes

The complete 200-item register, including implemented and planned work, is in docs/HARDENING_200.md.

Extended capability suite: 60 additional tools

The server exposes 100+ tools in total: the original 40 operational tools plus 60 focused capabilities from tools/capability_suite.py.

Tools that could cause broad mutations return a dry_run plan by default. Direct comment tools perform one visible comment operation per invocation. The capability catalog asserts 60 unique additions at import time, and Docker validation confirms 100 registered FastMCP tools in both source copies.

Distribution

Docker Image

The MCP server is distributed as a standalone Docker image. Build locally:

docker build -t github-project-mcp:latest ./mcp

CI/CD Pipeline

The mcp-ci.yaml workflow runs automatically on:

• Push to main when files under mcp/ change

• Pull requests touching mcp/ paths

Pipeline stages:

1. Build — Docker image build verification

2. Syntax check — AST parsing of all Python files

3. Unit tests — pytest suite execution

4. Tool count verification — Ensures ≥100 registered tools

Versioning

This MCP server follows Semantic Versioning. See CHANGELOG.md for release history.