Vikunja MCP для Codex

Используйте обычные предложения в Codex для чтения и управления задачами в вашем собственном аккаунте Vikunja.

Например, вы можете попросить Codex:

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

Вам не нужно вводить команды с / или упоминать плагин через @. Просто задавайте вопросы естественным образом в новой задаче Codex после установки.

Зачем нужен этот плагин

Vikunja и Codex сами по себе не говорят на одном языке:

• Vikunja предоставляет HTTP API для проектов и задач.

• Codex использует инструменты MCP, когда ему нужно работать с другим приложением.

• Этот плагин — небольшой мост, который преобразует MCP-запросы Codex в запросы к API Vikunja.

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

Плагин не заменяет Vikunja, не размещает вторую базу данных задач и не обращается напрямую к базе данных Vikunja. Vikunja по-прежнему управляет входами, разрешениями, проверкой и хранением.

Related MCP server: Vikunja MCP Server

Что он умеет

• Просматривать и создавать проекты Vikunja.

• Просматривать задачи в проекте.

• Создавать и обновлять задачи.

• Отмечать задачи как выполненные.

Операции удаления намеренно не включены в эту первую версию.

Установка для начинающих

Эти инструкции предназначены для тех, кто впервые настраивает новый компьютер с Codex.

1. Установите Codex CLI

Команды терминала в этом руководстве требуют Codex CLI, даже если вы также используете настольное приложение Codex.

На macOS или Linux используйте официальный установщик:

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

Для Windows и альтернативных методов установки следуйте официальному руководству по Codex CLI.

Откройте новый терминал, убедитесь, что он установлен, затем войдите:

codex --version
codex

Если терминал говорит codex: command not found, сначала закройте и снова откройте терминал. Если это не помогло, вернитесь к официальному руководству по установке и проверьте, что каталог установки Codex находится в вашем PATH.

2. Установите Node.js и Git

Установите:

• Node.js версии 20 или новее. Выберите текущий LTS-релиз, если у вас нет причин поступать иначе.

• Git, который используется при установке напрямую с GitHub.

Установка Node.js также устанавливает npm и npx. Проверьте всё из нового терминала:

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

Вам не нужно запускать npm install для обычного использования. Готовый MCP-сервер и его зависимости уже собраны в этом репозитории.

3. Установите плагин с GitHub

Этот репозиторий должен быть публичным по адресу DanJamesMills/vikunja-mcp, чтобы эти команды работали для других людей.

Добавьте репозиторий GitHub как маркетплейс плагинов Codex:

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

Установите из него плагин Vikunja:

codex plugin add codex-vikunja@vikunja-mcp

Подтвердите, что Codex его видит:

codex plugin list

После добавления маркетплейса плагин также можно просматривать и управлять им из каталога плагинов в настольном приложении Codex.

4. Создайте токен API Vikunja

Войдите в свой собственный сайт Vikunja и откройте:

Настройки → Токены API

Создайте выделенный токен с правами чтения и записи, которые вы хотите предоставить Codex. Скопируйте его, пока Vikunja его показывает.

5. Подключите плагин к Vikunja

Запустите пошаговую настройку:

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

Она запросит:

1. Ваш URL Vikunja, например https://tasks.example.com.

2. Ваш токен API Vikunja. Ввод токена скрыт.

Настройка проверяет соединение перед сохранением. Каждый пользователь вводит свой собственный URL и токен; этот публичный репозиторий не содержит ни того, ни другого.

npx просто загружает и запускает команду настройки из этого репозитория GitHub. Он входит в состав Node.js, поэтому отдельной установки npx не требуется.

6. Перезапустите Codex и протестируйте

Закройте и снова откройте Codex, или начните новую задачу Codex, чтобы загрузить только что установленный MCP-сервер. Затем спросите:

List my Vikunja projects.

После этого попробуйте запись:

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

Это полная настройка для обычного пользователя.

Будет ли это работать после перезапуска?

Да. Настройка сохраняет URL и токен в папке пользовательских данных приложения вашей операционной системы. Когда Codex снова запускает плагин, он автоматически читает тот же файл.

Настройки также сохраняются при обновлениях плагина. Вам не нужно экспортировать токен заново после перезапуска терминала, Codex или компьютера.

Проверка, изменение или удаление сохранённого подключения

Используйте эти команды в любое время:

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

• status сообщает, существуют ли настройки, но никогда не отображает токен.

• configure проверяет и сохраняет другой URL или токен.

• logout запрашивает подтверждение и удаляет сохранённый файл настроек.

После изменения или удаления подключения перезапустите Codex или откройте новую задачу. Удаление сохранённого подключения — это отдельная операция от удаления самого плагина. Чтобы удалить и сохранённое подключение, и установленный плагин, выполните:

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

Плагин также можно удалить из каталога плагинов Codex.

Где хранятся настройки

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

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

• Linux: $XDG_CONFIG_HOME/vikunja-mcp/config.json или ~/.config/vikunja-mcp/config.json

JSON-файл содержит URL Vikunja и токен API в открытом виде. На macOS и Linux настройка применяет права доступа только для владельца к каталогу и файлу (0700 и 0600). На Windows файл наследует права доступа к данным приложения текущего пользователя.

Защищайте свою учётную запись операционной системы, создавайте выделенный токен Vikunja только с необходимыми разрешениями и никогда не фиксируйте реальный токен или не вставляйте его в публичный issue. См. SECURITY.md.

Ранние тестовые версии использовали связку ключей macOS. Запуск setup или logout также очищает эту старую тестовую запись.

Несколько установок Vikunja

Публичный плагин работает с самостоятельно размещённым Vikunja и Vikunja Cloud, поскольку каждый пользователь предоставляет свой собственный URL и токен.

Эта версия поддерживает одну активную установку Vikunja на компьютер. Запустите configure, чтобы переключить её на другую установку.

Необязательные переменные окружения

Продвинутые пользователи и серверы могут предоставить настройки без файла настроек:

• VIKUNJA_URL

• VIKUNJA_API_TOKEN

Переменные окружения переопределяют сохранённые настройки. URL может быть как https://tasks.example.com, так и https://tasks.example.com/api/v1; плагин нормализует обе формы.

macOS и 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

Переменные, экспортированные в одном терминале, обычно исчезают при его закрытии. Пошаговая настройка проще для настольного использования, поскольку её настройки сохраняются между перезапусками.

Обновление плагина

Получите самую свежую информацию о маркетплейсе с GitHub:

codex plugin marketplace upgrade vikunja-mcp

Затем установите доступное обновление Vikunja из каталога плагинов или снова выполните команду установки плагина:

codex plugin add codex-vikunja@vikunja-mcp

Начните новую задачу Codex после обновления. Для производственных релизов установка из тегированного Git-релиза безопаснее, чем следование за main, поскольку версия фиксирована.

Включённые инструменты MCP

• vikunja_list_projects

• vikunja_create_project

• vikunja_list_tasks

• vikunja_create_task

• vikunja_update_task

• vikunja_complete_task

Большинству пользователей никогда не понадобятся эти названия; это внутренние инструменты, которые Codex выбирает из вашего запроса на естественном языке.

Для участников

Только участники, изменяющие исходный код плагина, должны клонировать репозиторий и установить зависимости для разработки:

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

Фиксируйте пересобранный mcp/server.bundle.mjs при каждом изменении исходного кода или зависимостей. Установленные пользователи запускают этот бандл, поэтому им не нужна локальная директория node_modules.

Протестируйте бандл для онбординга из клонированной копии:

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

Запустите проверку конфигурации с временными значениями:

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

Ввод токена скрыт. Никогда не помещайте реальный токен в аргумент команды, фикстуру, историю оболочки или Git-коммит.

Начните с docs/FOLDER-GUIDE.md, чтобы узнать, что делает каждый файл и как запрос проходит через плагин.

Публикация в npm

Пакет помечен как private, чтобы предотвратить случайную публикацию в npm. Установка с GitHub использует зафиксированный бандл и не требует пакета npm.

Если этот проект будет позже опубликован в npm, выберите и защитите имя пакета, удалите private, добавьте автоматизацию релизов, проверьте зависимости и публикуйте неизменяемые версии.