projectx-mcp

Registra horas en ProjectX hablando con Claude Desktop.

"Registra 8 horas de Ontrac para hoy" "Rellena los días que faltan esta semana con Ontrac" "¿Para qué días me faltan horas este mes?"

Instalación

macOS (automatizada)

git clone git@github.com:agustindiezdb/projectx-mcp.git
cd projectx-mcp
bash scripts/install.sh

El script hará lo siguiente:

• Instalará las dependencias

• Compilará el proyecto

• Configurará Claude Desktop automáticamente

• Creará una copia de seguridad de tu configuración existente

Luego reinicia Claude Desktop. Chrome se abrirá automáticamente para iniciar sesión con tu cuenta de Google de Dualboot.

¡Eso es todo! Ahora puedes pedirle a Claude que registre tus horas.

Windows

git clone git@github.com:agustindiezdb/projectx-mcp.git
cd projectx-mcp
npm install
npm run build

Luego edita manualmente la configuración de Claude Desktop:

Abre: %APPDATA%\Claude\claude_desktop_config.json

Añade:

{
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\projectx-mcp\\dist\\src\\server.js"]
    }
  }
}

Reemplaza C:\ruta\completa\a\ con tu ruta real (usa \ para rutas de Windows).

Luego reinicia Claude Desktop. Chrome se abrirá automáticamente para iniciar sesión.

Instalación manual

Si prefieres configurar manualmente:

1. Clona y compila:

   git clone git@github.com:agustindiezdb/projectx-mcp.git
   cd projectx-mcp
   npm install
   npm run build

2. Edita la configuración de Claude Desktop:
   Abre ~/Library/Application Support/Claude/claude_desktop_config.json y añade:

   {
     "mcpServers": {
       "projectx": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/projectx-mcp/dist/src/server.js"]
       }
     }
   }

   Reemplaza /RUTA/ABSOLUTA/A/ con la ruta completa a tu repositorio clonado.

3. Reinicia Claude Desktop

Uso con Cursor

Cursor utiliza una configuración MCP por proyecto. Crea .cursor/mcp.json en la raíz de tu proyecto:

{
  "$schema": "https://json.schemastore.org/mcp.json",
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/projectx-mcp/dist/src/server.js"]
    }
  }
}

Reemplaza /RUTA/ABSOLUTA/A/ con la ruta completa a tu repositorio clonado.

Luego reinicia Cursor. La primera vez, Chrome se abrirá para iniciar sesión.

Uso

Simplemente habla con Claude de forma natural:

Log 8 hours of Ontrac for today with description "Sprint planning"

Check my entries for this week and fill the missing days with 8h of Ontrac

Delete yesterday's entry and log 4h of Internal — Administrative

Which days am I missing hours for April?

Herramientas disponibles

Si el inicio de sesión falla o la sesión caduca

Simplemente reinicia Claude Desktop. Chrome se abrirá de nuevo para que inicies sesión.

Scripts útiles

Puedes usar la API directamente sin Claude Desktop:

# Test the API (creates and deletes a test entry)
npm run test:entry

# Check which days you're missing hours in April
npx ts-node scripts/check-april.ts

# Manually refresh your session (if expired)
npm run save-session

Para desarrolladores

Arquitectura

Claude Desktop → MCP Server (stdio) → fetch() + _interslice_session cookie → ProjectX API

La cookie de sesión se almacena en ~/Library/Application Support/projectx-mcp/auth.json (ignorada por git).

Al iniciar, si no se encuentra una sesión válida, Chrome se abre automáticamente para iniciar sesión a través de Playwright.

Modo de desarrollo

npm run dev

Esto ejecuta el servidor con ts-node para un desarrollo rápido (no se necesita paso de compilación).

Cómo funciona

1. Autenticación: Utiliza Playwright para abrir Chrome y detectar automáticamente cuándo el inicio de sesión es exitoso mediante sondeo a /api/v1/current_user

2. Persistencia de sesión: Guarda cookies en auth.json usando storageState() de Playwright

3. Cliente API: Lee la cookie _interslice_session y realiza solicitudes autenticadas a ProjectX

4. Protocolo MCP: Expone 4 herramientas a Claude Desktop a través del transporte stdio

Configuración de Claude Desktop (manual)

Si prefieres editar manualmente:

{
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["/path/to/projectx-mcp/dist/src/server.js"]
    }
  }
}

Solución de problemas

• Sesión caducada → reinicia Claude Desktop, Chrome se abrirá automáticamente

• Chrome no encontrado → instala Google Chrome (debe estar en el PATH del sistema)

• Proyecto no encontrado → pídele a Claude que ejecute get_projects para ver los nombres exactos

• Problemas de ruta (macOS/Linux) → usa rutas absolutas, no ~ ni rutas relativas

• Problemas de ruta (Windows) → usa \ (barra invertida doble) en las rutas JSON, p. ej. C:\Users\...

• Ubicación del archivo de autenticación:

  • macOS: ~/Library/Application Support/projectx-mcp/auth.json

  • Windows: %APPDATA%\projectx-mcp\auth.json

  • Linux: ~/.config/projectx-mcp/auth.json

Requisitos

• SO: macOS, Windows o Linux

• Node.js: 20+

• Navegador: Google Chrome (requerido para el inicio de sesión automático)

• Claude Desktop

• Cuenta de Google de Dualboot

Licencia

Herramienta interna para Dualboot Partners.