Vikunja MCP para Codex

Usa frases normales en Codex para leer y gestionar tareas en tu propia cuenta de Vikunja.

Por ejemplo, puedes pedirle a Codex:

Show my open Vikunja tasks.
Create a task called "Prepare the launch checklist" in my Website Redesign project.
Mark task 42 as complete.

No necesitas escribir comandos con / ni mencionar el plugin con @. Pregunta de forma natural en una nueva tarea de Codex después de la instalación.

Por qué existe este plugin

Vikunja y Codex no hablan el mismo idioma por sí solos:

• Vikunja proporciona una API HTTP para proyectos y tareas.

• Codex utiliza herramientas MCP cuando necesita trabajar con otra aplicación.

• Este plugin es el pequeño puente que traduce las solicitudes MCP de Codex en solicitudes a la API de Vikunja.

You → Codex → this plugin → your Vikunja API → your tasks

El plugin no reemplaza a Vikunja, no aloja una segunda base de datos de tareas ni accede directamente a la base de datos de Vikunja. Vikunja sigue controlando los inicios de sesión, permisos, validación y almacenamiento.

Related MCP server: Vikunja MCP Server

Qué puede hacer

• Listar y crear proyectos de Vikunja.

• Listar tareas en un proyecto.

• Crear y actualizar tareas.

• Marcar tareas como completadas.

Las operaciones de eliminación no están incluidas deliberadamente en esta primera versión.

Instalación para principiantes

Estas instrucciones son para alguien que configura un ordenador nuevo con Codex por primera vez.

1. Instalar la CLI de Codex

Los comandos de terminal de esta guía necesitan la CLI de Codex, incluso si también usas la aplicación de escritorio de Codex.

En macOS o Linux, usa el instalador oficial:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Para Windows y métodos de instalación alternativos, sigue la guía oficial de la CLI de Codex.

Abre una nueva terminal, confirma que está instalada y luego inicia sesión:

codex --version
codex

Si la terminal dice codex: command not found, cierra y vuelve a abrir la terminal primero. Si sigue fallando, vuelve a la guía de instalación oficial y comprueba que el directorio de instalación de Codex esté en tu PATH.

2. Instalar Node.js y Git

Instala:

• Node.js versión 20 o superior. Elige la versión LTS actual a menos que tengas una razón para no hacerlo.

• Git, que se usa al instalar directamente desde GitHub.

Instalar Node.js también instala npm y npx. Verifica todo desde una nueva terminal:

node --version
npm --version
npx --version
git --version

No necesitas ejecutar npm install para el uso normal. El servidor MCP terminado y sus dependencias ya están empaquetados en este repositorio.

3. Instalar el plugin desde GitHub

Este repositorio debe ser público en DanJamesMills/vikunja-mcp para que estos comandos funcionen para otras personas.

Añade el repositorio de GitHub como un mercado de plugins de Codex:

codex plugin marketplace add DanJamesMills/vikunja-mcp --ref main

Instala el plugin de Vikunja desde él:

codex plugin add codex-vikunja@vikunja-mcp

Confirma que Codex puede verlo:

codex plugin list

Una vez añadido el mercado, el plugin también se puede ver y gestionar desde el Directorio de Plugins en la aplicación de escritorio de Codex.

4. Crear un token de API de Vikunja

Inicia sesión en tu propio sitio web de Vikunja y abre:

Configuración → Tokens de API

Crea un token dedicado con los permisos de lectura y escritura que quieras que tenga Codex. Cópialo mientras Vikunja lo muestra.

5. Conectar el plugin a Vikunja

Ejecuta la configuración guiada:

npx --yes github:DanJamesMills/vikunja-mcp setup

Pregunta por:

1. Tu URL de Vikunja, por ejemplo https://tasks.example.com.

2. Tu token de API de Vikunja. La entrada del token está oculta.

La configuración comprueba la conexión antes de guardarla. Cada usuario introduce su propia URL y token; este repositorio público no contiene ninguno.

npx simplemente descarga y ejecuta el comando de configuración desde este repositorio de GitHub. Viene incluido con Node.js, por lo que no hay una instalación separada de npx.

6. Reiniciar Codex y probarlo

Cierra y vuelve a abrir Codex, o inicia una nueva tarea de Codex, para que se cargue el servidor MCP recién instalado. Luego pregunta:

List my Vikunja projects.

Prueba una escritura después de eso:

Create a task called "Test the Vikunja Codex plugin" in project 12.

Esa es la configuración completa para un usuario normal.

¿Seguirá funcionando después de un reinicio?

Sí. La configuración guarda la URL y el token en la carpeta de datos de aplicación del usuario de tu sistema operativo. Cuando Codex inicia el plugin de nuevo, lee el mismo archivo automáticamente.

La configuración también sobrevive a las actualizaciones del plugin. No necesitas exportar el token de nuevo después de reiniciar tu terminal, Codex o el ordenador.

Comprobar, cambiar o eliminar la conexión guardada

Usa estos comandos en cualquier momento:

npx --yes github:DanJamesMills/vikunja-mcp status
npx --yes github:DanJamesMills/vikunja-mcp configure
npx --yes github:DanJamesMills/vikunja-mcp logout

• status indica si existen ajustes pero nunca muestra el token.

• configure verifica y guarda una URL o token diferente.

• logout pide confirmación y elimina el archivo de ajustes guardado.

Después de cambiar o eliminar la conexión, reinicia Codex o abre una nueva tarea. Eliminar la conexión guardada es independiente de desinstalar el plugin en sí. Para eliminar tanto la conexión guardada como el plugin instalado, ejecuta:

npx --yes github:DanJamesMills/vikunja-mcp logout
codex plugin remove codex-vikunja@vikunja-mcp

El plugin también se puede desinstalar desde el Directorio de Plugins de Codex.

Dónde se almacenan los ajustes

• macOS: ~/Library/Application Support/vikunja-mcp/config.json

• Windows: %APPDATA%\vikunja-mcp\config.json

• Linux: $XDG_CONFIG_HOME/vikunja-mcp/config.json, o ~/.config/vikunja-mcp/config.json

El archivo JSON contiene la URL de Vikunja y el token de API en texto plano. En macOS y Linux, la configuración aplica permisos de directorio y archivo solo para el propietario (0700 y 0600). En Windows, el archivo hereda los permisos de datos de aplicación del usuario actual.

Protege tu cuenta del sistema operativo, crea un token de Vikunja dedicado con solo los permisos que necesites y nunca confirmes un token real ni lo pegues en una incidencia pública. Consulta SECURITY.md.

Las versiones de prueba tempranas usaban el Llavero de macOS. Ejecutar setup o logout también limpia esa entrada de prueba antigua.

Múltiples instalaciones de Vikunja

El plugin público funciona con Vikunja autoalojado y Vikunja Cloud porque cada usuario proporciona su propia URL y token.

Esta versión admite una instalación activa de Vikunja por ordenador. Ejecuta configure para cambiarla a una instalación diferente.

Variables de entorno opcionales

Los usuarios avanzados y servidores pueden proporcionar ajustes sin el archivo de configuración:

• VIKUNJA_URL

• VIKUNJA_API_TOKEN

Las variables de entorno anulan los ajustes guardados. La URL puede ser https://tasks.example.com o https://tasks.example.com/api/v1; el plugin normaliza ambas formas.

macOS y Linux

export VIKUNJA_URL="https://tasks.example.com"
export VIKUNJA_API_TOKEN="tk_your_token"
codex

Windows PowerShell

$env:VIKUNJA_URL = "https://tasks.example.com"
$env:VIKUNJA_API_TOKEN = "tk_your_token"
codex

Las variables exportadas en una terminal normalmente desaparecen cuando esa terminal se cierra. La configuración guiada es más sencilla para uso de escritorio porque sus ajustes persisten entre reinicios.

Actualizar el plugin

Obtén la información más reciente del mercado desde GitHub:

codex plugin marketplace upgrade vikunja-mcp

Luego instala la actualización disponible de Vikunja desde el Directorio de Plugins, o ejecuta de nuevo el comando de instalación del plugin:

codex plugin add codex-vikunja@vikunja-mcp

Inicia una nueva tarea de Codex después de actualizar. Para versiones de producción, instalar desde una versión etiquetada de Git es más seguro que seguir main porque la versión está fija.

Herramientas MCP incluidas

• vikunja_list_projects

• vikunja_create_project

• vikunja_list_tasks

• vikunja_create_task

• vikunja_update_task

• vikunja_complete_task

La mayoría de los usuarios nunca necesitan estos nombres; son las herramientas internas que Codex selecciona a partir de tu solicitud en lenguaje natural.

Para colaboradores

Solo los colaboradores que modifican el código fuente del plugin necesitan clonar el repositorio e instalar sus dependencias de desarrollo:

git clone https://github.com/DanJamesMills/vikunja-mcp.git
cd vikunja-mcp
npm install
npm test
npm run build

Confirma el mcp/server.bundle.mjs reconstruido cada vez que cambien el código fuente o las dependencias. Los usuarios instalados ejecutan ese paquete, por lo que no necesitan un directorio node_modules local.

Prueba el paquete de incorporación desde un clon del repositorio:

node mcp/server.bundle.mjs setup
node mcp/server.bundle.mjs status
node mcp/server.bundle.mjs logout

Ejecuta la comprobación de configuración con valores temporales:

VIKUNJA_URL="https://tasks.example.com" \
VIKUNJA_API_TOKEN="tk_test_token" \
npm run check

La solicitud del token está oculta. Nunca pongas un token real en un argumento de comando, fixture, historial del shell o commit de Git.

Empieza con docs/FOLDER-GUIDE.md para aprender qué hace cada archivo y cómo una solicitud atraviesa el plugin.

Publicación en npm

El paquete está marcado como private para evitar su publicación accidental en npm. La instalación desde GitHub utiliza el paquete confirmado y no requiere un paquete npm.

Si este proyecto se publica en npm más adelante, elige y asegura un nombre de paquete, elimina private, añade automatización de lanzamientos, audita las dependencias y publica versiones inmutables.