Vikunja MCP for 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 ツールを使用します。

• このプラグインは、Codex の MCP リクエストを Vikunja API リクエストに変換する小さな橋渡し役です。

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

このプラグインは Vikunja を置き換えるものではなく、セカンドタスクデータベースをホストしたり、Vikunja データベースに直接アクセスしたりしません。ログイン、権限、検証、ストレージは引き続き Vikunja が制御します。

Related MCP server: Vikunja MCP Server

できること

• Vikunja プロジェクトの一覧表示と作成

• プロジェクト内のタスクの一覧表示

• タスクの作成と更新

• タスクを完了としてマーク

削除操作は、この最初のバージョンでは意図的に含まれていません。

初心者向けインストール

これらの手順は、Codex を初めて使用する新しいコンピュータをセットアップする方向けです。

1. Codex CLI のインストール

このガイド内のターミナルコマンドは、Codex デスクトップアプリも使用する場合でも、Codex CLI が必要です。

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. Vikunja API トークンを作成

自分の Vikunja ウェブサイトにサインインし、以下を開きます。

設定 → API トークン

Codex に付与したい読み取り・書き込み権限を持つ専用トークンを作成します。Vikunja が表示している間にコピーしてください。

5. プラグインを Vikunja に接続

ガイド付きセットアップを実行します。

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

次の項目を尋ねられます。

1. Vikunja URL（例: https://tasks.example.com）

2. Vikunja API トークン。トークンの入力は隠されます。

セットアップは、接続を保存する前に接続を確認します。各ユーザーが自分の 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 ファイルには、Vikunja URL と API トークンがプレーンテキストで含まれています。macOS と Linux では、セットアップにより所有者のみがアクセスできるディレクトリとファイルの権限（0700 と 0600）が適用されます。Windows では、ファイルは現在のユーザーのアプリケーションデータ権限を継承します。

オペレーティングシステムのアカウントを保護し、必要な権限のみを持つ専用の Vikunja トークンを作成し、実際のトークンをコミットしたり公開 Issue に貼り付けたりしないでください。SECURITY.md を参照してください。

初期のテストバージョンでは macOS Keychain を使用していました。setup または logout を実行すると、その古いテストエントリもクリーンアップされます。

複数の Vikunja インストール

公開プラグインは、セルフホストの Vikunja と Vikunja Cloud の両方で動作します。各ユーザーが自分の URL とトークンを提供するためです。

このバージョンは、コンピュータごとに 1 つのアクティブな 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 タスクを開始してください。本番リリースでは、main を追跡するよりもタグ付けされた Git リリースからインストールする方が、バージョンが固定されているため安全です。

含まれる 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 を削除し、リリース自動化を追加し、依存関係を監査し、不変のバージョンを公開してください。