Vikunja tasks

emperor-vikunja

オープンソースのタスク管理ツールである Vikunja 用の MCP サーバーです。 Claude、 kowalski、または任意の MCP クライアントで、タスクの一覧表示、読み取り、作成、更新、コメントの追加、 プロジェクトの確認ができます。

emperor-mcp（Emperor Profile P1.1）を基盤としています。

• ステートレスな Streamable HTTP を /mcp で提供し、デスクトップクライアント向けに stdio にも対応しています。
• トークンは転送されるだけで、保存されません。 HTTP では各リクエストに固有の Authorization: Bearer <token> が含まれます。サーバーはそれを Vikunja に渡し、破棄します。デフォルトトークンやテストトークンはありません。
• 出力はフレーム化されています。 人が書いたタスクのテキスト（タイトル、説明、コメント）は、モデルへの指示ではなく、ユーザー向けのメッセージとしてモデルに渡されます。
• 明示的に指定しない限り、読み取り専用です。 オプションなしで起動すると、サーバーは読み取り用の 3 つのツールのみを提供します。--writable（または VIKUNJA_WRITABLE=true）を指定すると、タスクを変更する 3 つのツールが追加されます。
• 注釈付きの 6 つのツールは、コンパクトな定義を備えています。また、doctor サブコマンドを提供し、Markdown を入力として受け取り、プレーンテキストを出力します。
• 認証エラーが明確です。 Vikunja がトークンを拒否した場合、HTTP 経由の MCP レスポンスは 401 または 403 となり、クライアントは新しいトークンを求めることができます。

ツール

ツール	提供条件	注釈	機能
list_tasks	常時	読み取り専用	優先度、次に期限で並べ替えたタスクです。フィルター：project（タイトルまたは ID）、label、done（デフォルトは false）、due_before、search。limit は最大 100（デフォルトは 50）です。ID、タイトル、プロジェクト、ラベル、担当者、優先度、期限、完了状態を返します。
get_task	常時	読み取り専用	id で指定した 1 件のタスクです。すべてのフィールド、プレーンテキスト形式の説明（先頭から 20 000 文字）、および最新 50 件のコメント（投稿者と日付、各 4 000 文字）を返します。
create_task	--writable 指定時	書き込み、冪等ではない	project、title、省略可能な description（Markdown）、labels、create_missing_labels、assignees（ユーザー名）、priority 0-5、due を指定します。
update_task	--writable 指定時	書き込み、破壊的、冪等	id と、title、description、done、priority、due（"none" を指定するとクリア）、add_labels、remove_labels、create_missing_labels、add_assignees、remove_assignees、project（移動）のいずれかを指定します。
comment	--writable 指定時	書き込み、冪等ではない	タスク id に Markdown コメントを追加します。
list_projects	常時	読み取り専用	ID、タイトル、親プロジェクト、未完了タスク数を含むプロジェクト（最大 100 件）です。

--writable を指定しない場合、書き込みツールはサーバーに一切含まれません。リストにも表示されず、呼び出すこともできないため、モデルも、モデルが読み取るテキストも、これらのツールにアクセスできません。

すべてのツールはオープンワールドとしてマークされています（他の人が変更する Vikunja と通信します）。 update_task は破壊的としてマークされています。新しいタイトルや説明で古いテキストが置き換えられ、Vikunja は古いテキストを保持せず、ラベルや担当者も削除できるためです。また、同じ呼び出しを 2 回行っても、1 回行った場合と同じ状態になるため、冪等としてマークされています。

ラベルはタイトルで指定します。存在しないラベルは、呼び出しで create_missing_labels: true を渡さない限りエラーになります。そのため、誤入力によって新しいラベルが意図せず追加されることはありません。担当者はユーザー名で指定します（大文字と小文字を区別せず、完全一致。先頭に @ を付けてもかまいません）。書き込みの前に名前を確認するため、無効なラベルやユーザー名が指定されても、タスクが中途半端に作成されることはありません。

優先度：0 は未設定、1 は低、2 は中、3 は高、4 は緊急、5 は今すぐ対応です。日付：YYYY-MM-DD（00:00 UTC として読み取られます）または ISO-8601 形式です。日付は RFC 3339 形式で返され、未設定の場合は null が返されます。

説明とコメントは Vikunja によって HTML として保存されます。モデルが Markdown で書いた内容は、受け取り時に HTML に変換されます（Markdown 内の生の HTML はエスケープされ、そのまま通されることはありません）。読み戻した HTML はプレーンテキストに変換されます。

インストール

リリースからインストールする場合（Linux x86_64、macOS arm64 および x86_64、Windows x86_64）：お使いのプラットフォーム用のアーカイブをリリースからダウンロードし、emperor-vikunja を PATH に追加してください。

ソースからインストールする場合（Rust 1.88 以降）：

cargo install --git https://github.com/yarenty/emperor-vikunja

トークンを取得する

Vikunja で Settings > API Tokens > Create a token を開き、有効期限を選択して、次の権限にチェックを入れてください（--writable を指定した場合に 6 つのツールが必要とする最小限の権限です）。

グループ	権限
projects	read_all、read_one
tasks	read_all、read_one、create、update
tasks_comments	read_all、create
tasks_labels	read_all、create、delete
tasks_assignees	read_all、create、delete
labels	read_all、create（create_missing_labels を使う場合のみ create）
other	user（doctor でトークンの所有者を表示するため）、users（担当者をユーザー名で指定するため）

サーバーはデフォルトで読み取り専用です。読み取り専用のアシスタントには、read_all / read_one 権限のみ（および doctor 用に other: user）を付与したトークンを渡してください。

実行

ローカル（stdio）

export VIKUNJA_TOKEN=...            # from Settings > API Tokens
emperor-vikunja serve --stdio --base-url https://vikunja.example.com              # read-only
emperor-vikunja serve --stdio --base-url https://vikunja.example.com --writable   # also create, update, comment

Docker（stdio）

docker build -t emperor-vikunja https://github.com/yarenty/emperor-vikunja.git
docker run -i --rm -e VIKUNJA_URL=https://vikunja.example.com -e VIKUNJA_TOKEN emperor-vikunja
# read-only by default; to create, update and comment add -e VIKUNJA_WRITABLE=true
# (or --writable after the image name)

イメージは非 root ユーザーとして emperor-vikunja serve --stdio を実行します。Vikunja のアドレスは VIKUNJA_URL から取得します。

共通（HTTP）

# --writable: the users of this server may create, update and comment; leave it out for read-only
emperor-vikunja serve --base-url https://vikunja.example.com --bind 127.0.0.1:8034 --writable
# MCP endpoint: http://127.0.0.1:8034/mcp   liveness: http://127.0.0.1:8034/health

すべての MCP リクエストには Authorization: Bearer <token> を含める必要があります。トークンは各ユーザーが用意します。 このモードでは VIKUNJA_TOKEN は無視されるため、あるユーザーのトークンが別のユーザーのリクエストに使われることはありません。ツールの検出（tools/list）はトークンなしで機能します。

Vikunja がトークンを拒否する場合（401）、またはトークンに必要な権限がない可能性がある場合（403）、MCP レスポンスにはその HTTP ステータス（WWW-Authenticate: Bearer error="invalid_token" を伴う 401）と、コードが -32040、data.httpStatus を含む JSON-RPC エラーが含まれます。stdio 経由でも、クライアントは同じ JSON-RPC エラーを受け取ります。

フラグとヘッダー

フラグ	環境変数	意味
--base-url <URL>	VIKUNJA_URL	Vikunja のアドレスです。https://host と https://host/api/v1 のどちらも使用できます。--stdio では必須です。HTTP では、リクエストに X-Upstream-Url を指定する場合は省略できます。
--writable	VIKUNJA_WRITABLE	create_task、update_task、comment も提供します。指定しない場合、サーバーは読み取り専用となり、書き込みツールは拒否されるだけでなく、サーバーに含まれません。環境変数に true、1、yes、on を指定すると有効になります。未設定、空、false、0、no、off の場合は無効のままです。それ以外の値を指定すると、サーバーは起動時に停止します。
--read-only	VIKUNJA_READ_ONLY	非推奨で、効果はありません。読み取り専用がデフォルトです。既存の設定で起動できるよう引き続き受け付けますが、1 行のメモがログに記録されます。--writable と同時に指定すると、サーバーは起動を拒否します。
--stdio		標準入力／標準出力を介して MCP で通信します。トークンは VIKUNJA_TOKEN から取得します。
--bind <ADDR>		HTTP のリッスンアドレスです（デフォルトは 127.0.0.1:8034）。
--allowed-host <HOST>		この Host ヘッダーのみを受け付けます（複数回指定可能）。デフォルトでは無効で、前段に検証用プロキシを置く場合に使用します。
--allowed-origin <ORIGIN>		この Origin のみを受け付けます（複数回指定可能）。例：https://app.example.com。

リクエストヘッダー（HTTP）	意味
Authorization: Bearer <token>	呼び出し元の Vikunja API トークンです。すべてのツール呼び出しで必須です。
X-Upstream-Url: <URL>	このリクエストで使用する Vikunja インスタンスです。--base-url より優先されます。https が必須です。平文の http はループバックホスト（localhost、127.0.0.0/8、::1）の場合にのみ受け付けられます。

X-Upstream-Url を使うと、1 つのサーバーで複数の Vikunja インスタンスを受け付けられます。その場合、サーバーはクライアントが指定した任意の https ホストに、そのクライアントのトークンを使って接続します。任意のホストへの送信接続を許容できる環境で実行するか、プロキシでこのヘッダーを除外して --base-url を利用してください。

ログは stderr に出力されます。詳細を確認するには RUST_LOG=debug を設定してください。本番環境では、TLS を終端するリバースプロキシの背後に HTTP サーバーを配置してください（Emperor Profile E5）。

接続

Claude Desktop（claude_desktop_config.json）：

--writable を指定すると、Claude は作成、更新、コメントを行えます。読み取り専用で接続する場合は、この指定を外してください。

{
  "mcpServers": {
    "vikunja": {
      "command": "emperor-vikunja",
      "args": ["serve", "--stdio", "--base-url", "https://vikunja.example.com", "--writable"],
      "env": { "VIKUNJA_TOKEN": "<your token>" }
    }
  }
}

Claude Code：

# stdio, read-only (the default)
claude mcp add vikunja-ro --env VIKUNJA_TOKEN=<your token> -- \
  emperor-vikunja serve --stdio --base-url https://vikunja.example.com
# stdio, --writable: Claude may also create, update and comment
claude mcp add vikunja --env VIKUNJA_TOKEN=<your token> -- \
  emperor-vikunja serve --stdio --base-url https://vikunja.example.com --writable
# or against a running HTTP server (its own --writable decides what is listed)
claude mcp add --transport http vikunja http://127.0.0.1:8034/mcp \
  --header "Authorization: Bearer <your token>" \
  --header "X-Upstream-Url: https://vikunja.example.com"

kowalski（config.toml）：

[[mcp.servers]]
name = "vikunja"
transport = "stdio"
# --writable: the agent may create, update and comment; drop it for read-only.
command = ["emperor-vikunja", "serve", "--stdio", "--base-url", "https://vikunja.example.com", "--writable"]
# VIKUNJA_TOKEN is read from kowalski's environment.

# or over HTTP (the server's own --writable decides what is listed)
[[mcp.servers]]
name = "vikunja-http"
transport = "http"
url = "http://127.0.0.1:8034/mcp"
headers = { Authorization = "Bearer <your token>", X-Upstream-Url = "https://vikunja.example.com" }

Doctor

emperor-vikunja doctor はサーバーの起動前に設定を確認し、問題がある場合は 1 で終了します。そのため、スクリプトやコンテナのヘルスチェックで利用できます。

$ VIKUNJA_TOKEN=... emperor-vikunja doctor --base-url https://vikunja.example.com
emperor-vikunja 0.2.0 doctor
  [ok  ] base url        https://vikunja.example.com/
  [ok  ] vikunja api     Vikunja v2.7.1
  [ok  ] VIKUNJA_TOKEN   set (43 chars)
  [ok  ] vikunja login   token works for user alice
  [ok  ] mode            read-only: get_task, list_projects, list_tasks (pass --writable or VIKUNJA_WRITABLE=true for create_task, update_task, comment)
  [ok  ] listen address  127.0.0.1:8034 is free
  [ok  ] tool budget     3 of at most 8 tools
all good (0 warning(s))

URL の形式が正しいこと、GET /api/v1/info が応答すること、トークンが設定されていること（長さのみ表示）、GET /api/v1/user がトークンを受け付けること、指定モードで提供されるツール（デフォルトでは読み取りツール 3 つ、--writable 指定時は 6 つ。非推奨の --read-only が指定された場合は警告）、リッスンアドレスが使用可能であること（--stdio の場合は確認を省略）、およびツール数が emperor-mcp の上限内であることを確認します。HTTP モードで VIKUNJA_TOKEN が設定されていない場合、トークンはリクエストごとに渡されるため、トークンの行は警告になります。--stdio ではエラーになります。--base-url についても同様です。HTTP では未指定の場合に警告となり（リクエストで X-Upstream-Url を指定する必要があります）、--stdio ではエラーになります。

互換性

Vikunja v2.7（vikunja/vikunja イメージ）でテスト済みです。タスクは Vikunja のフィルター構文（done = false && project = 3 && labels in 5 && due_date < '...'）を使って GET /tasks 経由で一覧表示されます。代わりに /tasks/all を提供する旧リリースも自動的に検出されます。また、サーバーがフィルターの一部を無視する場合でも結果が正しくなるよう、すべてのフィルターをローカルで再適用します。

ビルドとテスト

cargo test                                               # unit, fake-Vikunja, MCP HTTP and stdio tests
cargo test --test live_vikunja -- --ignored --nocapture  # default and --writable against a real Vikunja in Docker

リンク

• クレート：crates.io/crates/emperor-vikunja、API ドキュメントは docs.rs
• コンテナー：Dockerfile からビルドします。stdio でサービスを提供し、VIKUNJA_URL、VIKUNJA_TOKEN、VIKUNJA_WRITABLE を読み込みます
• 公式 MCP Registry に mcp-name: io.github.yarenty/emperor-vikunja として掲載されています
• 他のタスク管理 MCP サーバーとの比較：docs/COMPARISON.md

ライセンス

以下のいずれかのライセンスが適用されます。

• Apache License, Version 2.0（LICENSE-APACHE または https://www.apache.org/licenses/LICENSE-2.0）
• MIT license（LICENSE-MIT または https://opensource.org/licenses/MIT）

お客様の選択に応じて適用されます。

お客様が明示的に別段の定めをしない限り、emperor-vikunja に含めるためにお客様が意図的に提出したコントリビューションには、追加の条件を付すことなく、上記の両方のライセンスが適用されます。