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 を初めて使用する新しいコンピュータをセットアップする方向けです。
このガイド内のターミナルコマンドは、Codex デスクトップアプリも使用する場合でも、Codex CLI が必要です。
macOS または Linux では、公式インストーラーを使用します。
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows および代替インストール方法については、公式 Codex CLI ガイド を参照してください。
新しいターミナルを開き、インストールを確認してからサインインします。
codex --version
codexターミナルで codex: command not found と表示された場合は、まずターミナルを閉じてから開き直します。それでも失敗する場合は、公式インストールガイドに戻り、Codex のインストールディレクトリが PATH に含まれているか確認してください。
以下をインストールします。
Node.js をインストールすると、npm と npx もインストールされます。新しいターミナルですべてを確認します。
node --version
npm --version
npx --version
git --version通常の使用では npm install を実行する必要はありません。完成した MCP サーバーとその依存関係は、このリポジトリに既にバンドルされています。
このリポジトリは他の人が上記のコマンドを使用するために、DanJamesMills/vikunja-mcp で公開されている必要があります。
GitHub リポジトリを Codex プラグインマーケットプレイスとして追加します。
codex plugin marketplace add DanJamesMills/vikunja-mcp --ref mainそこから Vikunja プラグインをインストールします。
codex plugin add codex-vikunja@vikunja-mcpCodex が認識できることを確認します。
codex plugin listマーケットプレイスを追加すると、Codex デスクトップアプリのプラグインディレクトリからプラグインを表示・管理することもできます。
自分の Vikunja ウェブサイトにサインインし、以下を開きます。
設定 → API トークン
Codex に付与したい読み取り・書き込み権限を持つ専用トークンを作成します。Vikunja が表示している間にコピーしてください。
ガイド付きセットアップを実行します。
npx --yes github:DanJamesMills/vikunja-mcp setup次の項目を尋ねられます。
Vikunja URL（例: https://tasks.example.com）
Vikunja API トークン。トークンの入力は隠されます。
セットアップは、接続を保存する前に接続を確認します。各ユーザーが自分の URL とトークンを入力します。この公開リポジトリにはどちらも含まれていません。
npx は単に、この GitHub リポジトリからセットアップコマンドをダウンロードして実行します。Node.js に含まれているため、別途 npx をインストールする必要はありません。
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 logoutstatus は設定が存在するかどうかを表示しますが、トークンは決して表示しません。
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 Cloud の両方で動作します。各ユーザーが自分の URL とトークンを提供するためです。
このバージョンは、コンピュータごとに 1 つのアクティブな Vikunja インストールをサポートします。configure を実行して、別のインストールに切り替えてください。
上級ユーザーやサーバーは、セットアップファイルを使用せずに設定を提供できます。
VIKUNJA_URL
VIKUNJA_API_TOKEN
環境変数は保存された設定より優先されます。URL は https://tasks.example.com または https://tasks.example.com/api/v1 のいずれでも構いません。プラグインは両方の形式を正規化します。
export VIKUNJA_URL="https://tasks.example.com"
export VIKUNJA_API_TOKEN="tk_your_token"
codex$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 リリースからインストールする方が、バージョンが固定されているため安全です。
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 を参照して、各ファイルの役割とリクエストがプラグイン内をどのように移動するかを学んでください。
このパッケージは private とマークされており、npm への誤った公開を防ぎます。GitHub からのインストールはコミットされたバンドルを使用し、npm パッケージは必要ありません。
このプロジェクトが後日 npm に公開される場合は、パッケージ名を選択して保護し、private を削除し、リリース自動化を追加し、依存関係を監査し、不変のバージョンを公開してください。
This server cannot be deployed
Manage projects, tasks, time tracking, and team collaboration through natural language.
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
