nexus-mcp

Servidor MCP que expone el sistema de gestión de proyectos Nexus/TaskBridge a Claude Code, para que los agentes puedan leer y actualizar tareas directamente en lugar de que una persona transmita el estado manualmente. Se complementa con dos skills en claude-templates — nexus-plan-work (para PM/BA/Team Lead, creación) y nexus-pick-up-task (para desarrolladores, consumo).

Se comunica con la API pública /api/v1/* del sistema de gestión de proyectos, no con los endpoints internos de nexus-vscode, que están reservados para las extensiones oficiales. Consulta DEVLOG.md para saber por qué y para ver el historial completo de desarrollo.

Configuración (una vez por persona)

Cuatro pasos, en orden: iniciar sesión no hace que Claude Code sepa por sí solo que nexus-mcp existe. Ese es un paso aparte (el 2 a continuación). No se necesita git clone en ningún momento de esta lista: npx descarga, compila y ejecuta directamente desde GitHub.

1. Inicia sesión — genera un token a través del Developer Portal y lo guarda en el llavero de tu sistema operativo (@napi-rs/keyring — nunca en un archivo):

export NEXUS_API_URL=http://27.254.62.17:8090
npx -y -p github:tanakorncode/nexus-mcp nexus-mcp-login

Te guía por $NEXUS_API_URL/developer → crea una app → concede los ámbitos tasks:read tasks:write projects:read members:read sprints:read → genera un token y luego te pide que pegues ese token junto con el correo de tu cuenta.

2. Regístrate en Claude Code — elige una opción (no hacen falta las dos, pero pueden convivir):

• Para ti, en todos los repos, una sola vez (necesita la CLI de claude — npm install -g @anthropic-ai/claude-code primero):

claude mcp add nexus-mcp -s user -e NEXUS_API_URL=http://27.254.62.17:8090 -- npx -y github:tanakorncode/nexus-mcp

Ya no hará falta ningún .mcp.json en ningún sitio después de esto.

• O bien, si un repositorio que vas a abrir ya tiene un .mcp.json confirmado en su raíz (p. ej. pea-thailand-backoffice-be), no tienes que hacer nada: Claude Code lo detecta solo al abrir ese repositorio. Solo es relevante si no has hecho el paso anterior.

3. Recarga Claude Code (nueva ventana / reinicia la sesión) — es necesario en cualquier caso; la sesión en ejecución no detecta por sí sola un servidor recién registrado. La primera conexión es más lenta (npx descarga y compila desde cero); después queda en caché. Acepta el aviso de confianza único.

4. Verifica — pide a Claude que llame a whoami. Si resuelve tu nombre, los cuatro pasos han funcionado.

Instala también los skills (una vez por persona; consulta claude-templates/README.md para más detalles):

mkdir -p ~/.claude/skills
git clone --depth 1 https://github.com/tanakorncode/claude-templates /tmp/claude-templates
cp -r /tmp/claude-templates/skills/nexus-pick-up-task ~/.claude/skills/
cp -r /tmp/claude-templates/skills/nexus-plan-work ~/.claude/skills/

Desarrollo del propio nexus-mcp

Si vas a modificar el código de este repositorio y no solo usarlo, clónalo para que los cambios surtan efecto sin tener que volver a publicar:

git clone https://github.com/tanakorncode/nexus-mcp
cd nexus-mcp
npm install
npm run build
npm link          # makes the `nexus-mcp` command available anywhere on this machine

Apunta .mcp.json a "command": "nexus-mcp" (sin args) en lugar de la forma con npx mientras iteras; recompila (npm run build) y recarga la ventana de Claude Code para aplicar los cambios; de lo contrario, el proceso del servidor MCP mantiene el código antiguo en memoria.

Related MCP server: Dooray MCP Server

Los dos skills y cuándo aplica cada uno

• nexus-plan-work — desglosar una funcionalidad en épica/historia/tarea. Úsalo antes de que exista el trabajo. La disciplina que importa aquí: una historia por funcionalidad que abarque varios repos, una tarea por repositorio debajo de ella y repositoryId establecido en cada tarea (el campo que más se suele omitir y el que luego es irrecuperable si se pasa por alto).

• nexus-pick-up-task — encontrar, entender y ejecutar una tarea, terminando en un PR y una actualización de estado. Úsalo una vez que el trabajo exista y alguien (una persona o una comprobación programada) esté listo para actuar sobre él.

Lee los propios archivos de los skills para ver el paso a paso completo; este README no los va a duplicar.

Herramientas

Identidad y descubrimiento

Lectura de tareas

Creación (consulta nexus-plan-work)

Entrega

Opcional: comprobación programada de tareas (solo notificación)

scripts/check-my-tasks.sh se ejecuta en modo headless (claude -p) y comprueba list_my_tasks con un temporizador, lanzando una notificación de macOS si hay algo listo. No empieza a escribir código por sí solo (--allowedTools está limitado a herramientas de solo lectura más Bash(osascript*), por lo que estructuralmente no puede editar archivos ni aunque quisiera).

launchctl load ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist   # enable, runs every 2h
launchctl unload ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist # disable
tail -f ~/Library/Logs/nexus-task-check.log                                     # watch it run
./scripts/check-my-tasks.sh                                                     # run once, right now

El plist en sí no está en este repositorio (es configuración local de cada máquina, por persona): copia el de la entrada del 2026-08-22 de DEVLOG.md o pregunta a quien lo haya configurado.

Esto solo comprueba; una persona aún tiene que abrir Claude Code y dar el visto bueno cuando reciba el aviso. Consulta DEVLOG.md si quieres saber por qué se queda ahí.

Limitaciones conocidas

• No hay soporte de comentarios ni de enlazado de commits: esas rutas solo existen en la API interna exclusiva de la extensión, no en /api/v1/*. Habría que añadir rutas nuevas en pm-system.

• No se pueden crear épicas por API: las épicas son poco frecuentes y las planifican los líderes; usa la interfaz del producto.

• No se pueden subir adjuntos ni embebidos por API (leerlos sí funciona: get_task devuelve ambos). Adjunta enlaces o capturas de Figma a través de la interfaz del producto.

• Las consultas filtradas por repositorio, historia o etiqueta solo devuelven resultados cuando alguien establece repositoryId/storyId/labelIds en las tareas; no se infiere nada automáticamente.