Gooseworks MCP

Un servidor Express que expone herramientas a través del transporte HTTP Streamable del Model Context Protocol (MCP), incluyendo un conjunto de herramientas de GitHub.

El endpoint MCP es:

http://localhost:4000/mcp

Cada solicitud debe incluir el token de portador configurado mediante MCP_AUTH_TOKEN.

Requisitos

• Node.js v25.2.1

• pnpm 11.5.3

• Docker Engine y Docker Compose v2 para despliegue en contenedores

• Un token de acceso personal de GitHub con los permisos requeridos por las herramientas que planeas usar

Related MCP server: GitHub MCP Agent Server

Configuración

El servidor carga variables desde un archivo local .env o del entorno del proceso:

Crea un archivo de entorno local a partir de la plantilla:

cp .env.template .env

Edita .env y reemplaza ambos valores de token de marcador de posición. Usa un valor largo y generado aleatoriamente para MCP_AUTH_TOKEN, y otorga al token de GitHub solo los permisos necesarios para este servidor. Nunca hagas commit de .env ni pegues ninguno de los tokens en un issue público, registro o imagen.

Ejecutar Localmente

1. Instala las dependencias:

   pnpm install

2. Crea y configura .env como se describió anteriormente.

3. Inicia el servidor:

   pnpm start

   Esto ejecuta el mismo punto de entrada que pnpm exec tsx src/index.ts.

Para desarrollo con reinicio automático después de cambios en el código fuente, usa:

pnpm dev

Para verificar el proyecto TypeScript sin generar archivos:

pnpm typecheck

El servidor está listo cuando la consola informa que está activo en http://localhost:<PORT>/mcp. Configura tu cliente MCP para usar esa URL y enviar:

Authorization: Bearer <MCP_AUTH_TOKEN>

Desplegar con Docker Compose

1. Instala Docker Engine con Docker Compose v2 en el host.

2. Clona este repositorio y entra en su directorio:

   git clone <repository-url>
   cd gooseworks-mcp

3. Crea el archivo de entorno de despliegue:

   cp .env.template .env

4. Establece GITHUB_TOKEN y un MCP_AUTH_TOKEN fuerte y privado en .env. Establece PORT si el servicio debe escuchar en un puerto diferente del host/contenedor. Se usa el mismo valor para ambos lados del mapeo de puertos de Compose.

5. Construye e inicia el servicio en segundo plano:

   docker compose up --build -d

6. Sigue los registros del servicio o detenlo cuando sea necesario:

   docker compose logs -f gooseworks-mcp
   docker compose down

La configuración de Compose pasa las tres variables soportadas al contenedor y falla temprano si falta alguno de los tokens requeridos. Para un despliegue público, coloca el servicio detrás de un proxy inverso HTTPS y mantén el puerto 4000 o tu PORT elegido privado cuando sea posible. Los clientes MCP deben usar la URL HTTPS /mcp del proxy y el token de portador configurado.

Herramientas Disponibles

El servidor registra las siguientes herramientas:

GitHub

• Lectura del perfil autenticado

• Listado de repositorios, ramas y commits

• Búsqueda de código

• Lectura de contenido de archivos

• Creación de issues

• Creación de pull requests

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Es libre de usar, bifurcar, modificar y redistribuir para cualquier propósito, sujeto a los términos de la licencia.