QTask
Servidor MCP de tareas/proyectos con OAuth para Claude, puente Cursor, búsqueda semántica, aprobación de escritura por etapas
Documentación
QTask
Gestión de tareas de código abierto con un servidor MCP integrado: conéctate a Claude Desktop, Cursor o cualquier cliente MCP.
Funciona con: Claude Desktop · Cursor · Ollama (agente local)
Producción: https://qtask.dev · Guía de configuración de MCP · Guía de usuario · Contribuye en GitHub
- Servidor MCP — lista, crea y actualiza tareas y proyectos desde Claude Desktop, Cursor u otros clientes MCP
- Escrituras por etapas — la IA externa propone cambios; tú los apruebas antes de que se apliquen
- Búsqueda semántica — encuentra tareas por significado, no solo por palabras clave
- Autohospedado — tus datos permanecen en tu infraestructura, con backends de IA intercambiables (Ollama, modelos compatibles con MCP)
Requisitos previos
- Node.js 20+
- Docker (para MongoDB)
- Ollama con modelos que admitan herramientas:
ollama pull qwen3.5:2b
ollama pull nomic-embed-text
Si actualizas una instalación existente, configura OLLAMA_MODEL=qwen3.5:2b en .env y descarga el modelo anterior.
Inicio rápido
docker compose up -d
cp .env.example .env
# Set JWT_SECRET in .env
# Optional: cp .env.local.example .env.local # secrets / overrides (gitignored)
npm install
npm install --prefix client
npm run dev:all
- API: http://localhost:3000
- Cliente web: http://localhost:5173
Crea una cuenta en la primera visita. Para secretos locales (por ejemplo, clave de API de Resend), usa .env.local — anula .env y no se incluye en el repositorio. En el servidor de producción, coloca esos valores en .env en su lugar (consulta docs/DEPLOY.md).
Documentación
| Doc | Audiencia |
|---|---|
| docs/MCP.md | Clientes de IA externos — comienza aquí para Claude Desktop y Cursor (claves de API, OAuth, etapas) |
| docs/USER_GUIDE.md | Usuarios finales — proyectos, tareas, agente, compartir |
| docs/QTask_Product_Requirements.md | Especificación del producto |
| docs/DEPLOY.md | Operadores — implementación local y de producción |
En la aplicación web, los usuarios con sesión iniciada pueden abrir Ayuda desde el menú de la cuenta.
Scripts
| Comando | Descripción |
|---|---|
npm run dev | Solo API de backend |
npm run dev:client | Solo cliente web React |
npm run dev:all | Backend + cliente web |
npm run mcp | Servidor MCP stdio (desarrollo local / Cursor) |
npm run mcp:bridge | Puente stdio a /api/mcp alojado |
npm test | Ejecutar pruebas de integración |
npm run build | Compilar API |
npm start | Iniciar API de producción (sirve al cliente web) |
Autenticación
Cuentas de correo/contraseña con JWT. Todas las rutas de API excepto /health y /api/auth/* requieren Authorization: Bearer <token>.
MCP en Cursor
Inicia sesión a través del cliente web, copia tu JWT y configura MCP_JWT en tu configuración MCP de Cursor. Consulta mcp-config.example.json.
Para qtask.dev alojado, crea una clave de API MCP en Menú de cuenta → IA externa (MCP) y usa npm run mcp:bridge. Consulta docs/MCP.md.