Configuración

Código Abierto — GitScrum MCP Server es código abierto bajo la licencia MIT. Disponible en npm y en GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor y cualquier cliente compatible con MCP tienen acceso operacional completo a tu stack de gestión de proyectos.

Esta guía cubre la configuración detallada para cada cliente MCP compatible, variables de entorno, uso con Docker, argumentos personalizados y pasos de verificación. Si seguiste el Inicio Rápido y necesitas opciones de configuración más avanzadas, esta es tu referencia.

Claude Desktop

Claude Desktop lee su configuración MCP de un archivo JSON en tu sistema de archivos local.

Ubicación del archivo de configuración

Si el archivo no existe, créalo manualmente. Asegúrate de que los directorios padre existan.

Configuración mínima

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Esto le indica a Claude Desktop que inicie el GitScrum MCP Server usando npx, que descarga y ejecuta la última versión automáticamente.

Agregar a configuración existente

Si ya tienes otros servidores MCP configurados, agrega gitscrum como una nueva entrada en el objeto mcpServers:

{
  "mcpServers": {
    "other-server": {
      "command": "other-command",
      "args": ["other-args"]
    },
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Usando una instalación global

Si instalaste el servidor globalmente con npm install -g @gitscrum-studio/mcp-server, referencia el binario directamente:

{
  "mcpServers": {
    "gitscrum": {
      "command": "gitscrum-mcp-server"
    }
  }
}

Con variables de entorno

Para pasar variables de entorno al proceso del servidor MCP:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"],
      "env": {
        "GITSCRUM_API_URL": "https://services.gitscrum.com"
      }
    }
  }
}

Aplicar cambios

Reinicia Claude Desktop después de editar el archivo de configuración. Claude Desktop lee la configuración solo al iniciar. Después de reiniciar, las herramientas de GitScrum aparecen automáticamente en el listado de herramientas de Claude.

VS Code con GitHub Copilot

GitHub Copilot lee las configuraciones de servidores MCP de un archivo JSON en tu workspace o configuración de usuario.

Configuración del workspace (por proyecto)

Crea o edita .vscode/mcp.json en el directorio raíz de tu proyecto:

{
  "servers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Esta configuración se aplica solo al workspace actual. Los miembros del equipo que abran el mismo proyecto también tendrán el GitScrum MCP Server configurado automáticamente si el archivo se incluye en el control de versiones.

Configuración a nivel de usuario (global)

Para hacer que el GitScrum MCP Server esté disponible en todos los workspaces de VS Code, agrégalo a la configuración de usuario de VS Code. Abre configuración (Ctrl+, / Cmd+,), busca "mcp" y agrega la configuración del servidor. Alternativamente, edita settings.json:

{
  "mcp": {
    "servers": {
      "gitscrum": {
        "command": "npx",
        "args": ["-y", "@gitscrum-studio/mcp-server"]
      }
    }
  }
}

Verificación

Después de guardar la configuración:

1. Abre el panel de chat de GitHub Copilot
2. Escribe: "Lista mis workspaces de GitScrum"
3. Copilot debería invocar el servidor MCP y devolver los datos de tu workspace

Si las herramientas no aparecen, recarga la ventana: Ctrl+Shift+P → "Developer: Reload Window".

Cursor

Cursor soporta servidores MCP a través de su sistema de configuración.

Ubicación del archivo de configuración

Configuración

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Via la interfaz de configuración de Cursor

Alternativamente, navega a Configuración de Cursor → MCP y agrega un nuevo servidor:

• Nombre: gitscrum
• Comando: npx
• Argumentos: -y @gitscrum-studio/mcp-server

Aplicar cambios

Reinicia Cursor después de editar la configuración. Las herramientas de GitScrum aparecen en el listado de herramientas en el panel de IA de Cursor.

Windsurf

Windsurf lee la configuración MCP desde su archivo de configuración.

Configuración

Agrega a tu configuración MCP de Windsurf:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Reinicia Windsurf después de guardar para activar el servidor.

Continue (VS Code / JetBrains)

Continue soporta servidores MCP a través de su archivo de configuración.

Archivo de configuración

Edita ~/.continue/config.json y agrega el servidor de GitScrum al array mcpServers:

{
  "mcpServers": [
    {
      "name": "gitscrum",
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  ]
}

Si ya tienes otros servidores MCP en el array, agrega la entrada de GitScrum:

{
  "mcpServers": [
    {
      "name": "other-server",
      "command": "other-command",
      "args": ["other-args"]
    },
    {
      "name": "gitscrum",
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  ]
}

Variables de entorno

El GitScrum MCP Server reconoce las siguientes variables de entorno:

Configurar variables de entorno

En la configuración del cliente (recomendado para configuraciones por servidor):

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"],
      "env": {
        "GITSCRUM_TOKEN": "tu-token-aqui"
      }
    }
  }
}

A nivel de shell (se aplica a todos los procesos):

# macOS/Linux
export GITSCRUM_TOKEN=tu-token-aqui

# Windows PowerShell
$env:GITSCRUM_TOKEN = "tu-token-aqui"

# Windows CMD
set GITSCRUM_TOKEN=tu-token-aqui

Importante: GITSCRUM_TOKEN omite el flujo OAuth seguro. Úsalo solo en pipelines CI/CD o entornos automatizados donde la autenticación basada en navegador no es práctica. Para uso interactivo, siempre usa el flujo OAuth Device Grant.

Uso con Docker

Si ejecutas entornos de desarrollo en contenedores Docker, puedes incluir el servidor MCP en tu configuración de Docker.

Dockerfile

FROM node:18-alpine

RUN npm install -g @gitscrum-studio/mcp-server

ENTRYPOINT ["gitscrum-mcp-server"]

Docker Compose con montaje de volumen

Para persistir la autenticación entre reinicios del contenedor, monta el directorio de tokens:

services:
  mcp:
    image: node:18-alpine
    command: npx -y @gitscrum-studio/mcp-server
    volumes:
      - ~/.gitscrum:/root/.gitscrum

Docker con variable de entorno

Para entornos containerizados, pasa el token directamente:

services:
  mcp:
    image: node:18-alpine
    command: npx -y @gitscrum-studio/mcp-server
    environment:
      - GITSCRUM_TOKEN=${GITSCRUM_TOKEN}

Nota: Al ejecutar en Docker, el flujo OAuth Device Grant puede no funcionar como se espera ya que el servidor MCP se ejecuta dentro del contenedor pero el navegador está en el host. Usa GITSCRUM_TOKEN para entornos Docker.

Argumentos personalizados del servidor

El servidor MCP acepta los siguientes argumentos de línea de comandos:

Verificar la versión instalada

npx -y @gitscrum-studio/mcp-server --version

Verificar la conexión

Después de configurar tu cliente, verifica que el servidor MCP está funcionando correctamente.

Paso 1: Verificar que el servidor inicia

Pregunta a tu asistente de IA:

Verifica el estado de autenticación de GitScrum

Si el servidor está ejecutándose, recibirás una respuesta sobre tu estado de autenticación (ya sea "autenticado" o "no autenticado").

Paso 2: Autenticarse

Si no estás autenticado, inicia sesión:

Inicia sesión en GitScrum

Completa el flujo OAuth basado en navegador como se describe en Autenticación.

Paso 3: Probar una operación de lectura

Después de autenticarte, prueba con una lectura simple:

Lista mis workspaces de GitScrum

Deberías ver los nombres de tus workspaces. Esto confirma:

• El servidor MCP está ejecutándose
• La autenticación funciona
• La conexión con la API es válida
• Tu cuenta tiene acceso al workspace

Paso 4: Probar una operación de escritura

Crea una tarea de prueba para verificar el acceso de escritura:

Crea una tarea llamada "Prueba del servidor MCP" en [nombre de tu proyecto]

Si la tarea se crea correctamente, tu servidor MCP está completamente operativo.

Actualizar el MCP Server

Con npx (automático)

Si usas npx -y @gitscrum-studio/mcp-server en tu configuración, las actualizaciones son automáticas. Cada vez que el servidor MCP inicia, npx verifica la última versión y la descarga si hay una versión más nueva disponible.

Para forzar una actualización a la última versión:

npx -y @gitscrum-studio/mcp-server@latest --version

Con instalación global

Si lo instalaste globalmente, actualiza manualmente:

npm update -g @gitscrum-studio/mcp-server

Verifica tu versión actual:

npm list -g @gitscrum-studio/mcp-server

Fijar versión

Para fijar a una versión específica (útil para equipos que necesitan comportamiento consistente):

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server@1.2.3"]
    }
  }
}

Reemplaza 1.2.3 con el número de versión deseado. Esto previene actualizaciones automáticas y asegura que todos los miembros del equipo usen la misma versión.

Resumen de configuración

Referencia rápida para todos los clientes compatibles:

Todos los clientes usan el mismo comando del servidor MCP:

npx -y @gitscrum-studio/mcp-server

Solución de problemas de configuración

Errores de sintaxis JSON

Los archivos de configuración deben contener JSON válido. Errores comunes:

• Comas finales después de la última propiedad en un objeto
• Comillas faltantes alrededor de claves o valores de cadena
• Comillas simples en lugar de comillas dobles

Usa un validador JSON o el modo de lenguaje JSON de tu editor para detectar errores de sintaxis antes de guardar.

Problemas de caché de npx

Si npx no detecta una nueva versión:

# Limpiar la caché de npx
npx clear-npx-cache

# O especificar latest explícitamente
npx -y @gitscrum-studio/mcp-server@latest

Errores de permisos en el archivo de token

Si el servidor MCP no puede leer o escribir ~/.gitscrum/auth.json:

# macOS/Linux: Corregir permisos
mkdir -p ~/.gitscrum
chmod 700 ~/.gitscrum
chmod 600 ~/.gitscrum/auth.json

# Windows PowerShell: Verificar que eres el propietario del archivo
Get-Acl "$env:USERPROFILE\.gitscrum\auth.json" | Format-List

Node.js no encontrado

Si el cliente reporta que npx o node no se encuentra, asegúrate de que Node.js esté en el PATH de tu sistema. Algunos clientes (especialmente aplicaciones de escritorio) pueden no heredar el PATH de tu shell. Puedes proporcionar la ruta completa a npx:

{
  "mcpServers": {
    "gitscrum": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

En Windows, usa la ruta completa:

{
  "mcpServers": {
    "gitscrum": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Usando MCP Inspector para depuración

La herramienta MCP Inspector te permite interactuar con el servidor MCP directamente, sin pasar por el cliente de IA:

npx @modelcontextprotocol/inspector node dist/index.js

Esto abre un inspector basado en navegador donde puedes llamar herramientas individuales y ver las respuestas en crudo. Útil para verificar que el servidor funciona independientemente de la configuración de tu cliente de IA.

Próximos pasos

• Inicio Rápido: Instalación rápida y primeros comandos.
• Autenticación: Profundización en el flujo OAuth 2.0 Device Grant.
• Seguridad: Modelo de seguridad empresarial y mejores prácticas.
• Descripción General de MCP: Referencia completa de herramientas con las 29 herramientas y más de 160 operaciones.