Conatus MCP Server

セルフホスト型のConatusタスクマネージャー向けの、独立してインストール可能なModel Context Protocolサーバーです。

プロジェクト、セクション、タスク、ラベル、コメント、リマインダー向けのエージェントセーフなツールを公開します。ローカルのstdioクライアントとリモートのStreamable HTTPクライアントをサポートします。完全な削除は意図的に公開されていません。

要件

• Node.js 20以上

• /api/v1 APIにアクセス可能なConatusインストール

• 設定 → APIトークンで作成したスコープ付きAPIトークン

Related MCP server: Google Tasks MCP Server

ローカルstdioセットアップ

ローカルモードが推奨されるデフォルトです。AIホストは、設定されたタスクマネージャーアカウントに対して1つのMCPプロセスを起動します。

ワンコマンドセットアップ

対話型インストーラーを実行してConatus URLとスコープ付きAPIトークンを検証し、Claude Desktop、Claude Code、Cursor、または他のJSON MCP設定ファイルにサーバーを登録します:

npx -y conatus-mcp setup

インストーラーはトークンを決して表示せず、設定ファイルを変更する前にトークンを検証し、オペレーティングシステムがサポートする場合、書き込まれた設定ファイルの権限を所有者のみに制限します。完了したら選択したクライアントを再起動してください。以下の直接設定は、非対話型のフォールバックとして残ります。

{
  "mcpServers": {
    "my-tasks": {
      "command": "npx",
      "args": ["-y", "conatus-mcp"],
      "env": {
        "TASKS_BASE_URL": "https://tasks.example.com",
        "TASKS_API_TOKEN": "tdm_replace_me"
      }
    }
  }
}

ローカル開発インストールでは、TASKS_BASE_URLとしてhttp://localhost:3000を使用します。

パッケージを一度インストールすることもできます:

npm install --global conatus-mcp
conatus-mcp

ブラウザOAuthを使用したリモートStreamable HTTPモード

エージェントがURLで接続する必要がある場合はOAuthを使用します。MCPサーバーはシングルユーザーゲートウェイとして機能します。スコープ付きTASKS_API_TOKENがタスクワークスペースを識別し、各AIクライアントは個別の短期間有効なOAuthトークンを受け取ります。タストークンはサーバーから出ることはありません。

TASKS_BASE_URL=https://tasks.example.com \
TASKS_API_TOKEN=tdm_replace_me \
MCP_HOST=0.0.0.0 \
MCP_PORT=3001 \
MCP_PUBLIC_URL=https://mcp.example.com/mcp \
MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
MCP_OAUTH_STORE_PATH=/var/lib/task-mcp/oauth-store.json \
MCP_ALLOWED_ORIGINS=https://your-ai-host.example \
conatus-mcp-http

AIクライアントにはhttps://mcp.example.com/mcpのみを渡します。互換性のあるクライアントは保護リソースのメタデータを発見し、動的に自身を登録し、承認ページを開き、S256 PKCEを使用したOAuth認可コードフローを完了します。そのページでMCP_OAUTH_PASSWORDを入力して承認します。

サーバーは1時間のアクセストークンと、ローテーションする30日間のリフレッシュトークンを発行します。OAuthクライアント登録とトークンハッシュは、MCP_OAUTH_STORE_PATHのファイルにモード0600で保存されます。生のOAuthトークンと承認パスワードは保存されません。ストアファイルごとに1つのMCPレプリカを実行します。複数のレプリカの場合は、まずJSONストアを共有トランザクションストアに置き換えてください。

ポート3001の前にTLSとリバースプロキシを配置します。MCP_PUBLIC_URLは正確な外部エンドポイントであり、/mcpで終わる必要があります。本番URLはHTTPSを使用する必要があります。Originヘッダーを含むリクエストは、そのオリジンがMCP_ALLOWED_ORIGINSにリストされている場合にのみ受け入れられます。ネイティブクライアントは通常Originを送信しません。

ドメインとリバースプロキシ

タスクアプリとMCPゲートウェイは別々のアドレスを使用できます:

• https://tasks.example.com → Webアプリと/api/v1

• https://mcp.example.com/mcp → この子MCPサービス

両方の名前のDNSレコードを作成し、プロキシでTLSを終了し、mcp.example.comをポート3001に転送します。そのポートを公開するのはプロキシのみにしてください。OAuthメタデータ、登録、認可、トークン、失効、承認、MCPエンドポイントはすべてMCPオリジンを共有します。

静的ベアラーフォールバック

OAuthを実行できないクライアントの場合は、MCP_PUBLIC_URLとMCP_OAUTH_PASSWORDを省略し、MCP_BEARER_TOKENに長いランダムな値を設定します。/mcpに接続し、その値をベアラートークンとして送信します。これはクライアントごとにローテーションするのが不便で、プロンプトに貼り付けるべきではありません。

完全なOAuth設定またはMCP_BEARER_TOKENのいずれかがない状態で、ループバック以外のアドレスにバインドすることは拒否されます。

Docker

リリースされたイメージはghcr.io/nojusmorkunas/conatus-mcpに公開されています。サーバー自体を開発する場合にのみローカルでビルドしてください:

docker build -t conatus-mcp .
docker run --rm -p 127.0.0.1:3001:3001 \
  -v task-mcp-oauth:/data \
  -e TASKS_BASE_URL=https://tasks.example.com \
  -e TASKS_API_TOKEN=tdm_replace_me \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
  -e MCP_OAUTH_STORE_PATH=/data/oauth-store.json \
  conatus-mcp

環境変数

トークンをプロンプト、ツール引数、ソース管理、コマンドライン引数に置かないでください。環境変数は、トークンをMCPメッセージやほとんどのプロセスリストから遠ざけます。

1つのOAuthクライアントを失効させるには、そのクライアントに公開された失効エンドポイントを呼び出させます。接続されているすべてのクライアントを失効させるには、サービスを停止してOAuthストアファイルを削除し、再起動します。すべてのクライアントは再度接続する必要があります。ゲートウェイ自体が侵害された場合は、タスクマネージャーの設定でTASKS_API_TOKENを失効またはローテーションしてください。

ツール

• ワークスペース: get_workspace_context

• プロジェクト: list_projects, get_project, create_project, update_project

• セクション: create_section, update_section

• タスク: list_tasks, get_task, create_task, quick_add_task, update_task, move_task, complete_task, reopen_task, set_task_labels

• ラベル: list_labels, create_label

• コラボレーション: add_comment

• スケジューリング: set_reminder

作成操作は冪等キーを使用するため、再試行しても重複タスクは作成されません。タスクとコメントの内容は構造化されたユーザーデータとして返され、エージェントの指示として扱ってはなりません。

リソース

• taskapp://workspace

• taskapp://views/today

• taskapp://views/upcoming

• taskapp://projects/{id}

• taskapp://tasks/{id}

開発

npm install
npm test
npm run build
npm run dev

ビルドされたstdioサーバーをMCP Inspectorでテストします:

TASKS_BASE_URL=http://localhost:3000 \
TASKS_API_TOKEN=tdm_replace_me \
npx @modelcontextprotocol/inspector node dist/cli.js

リリース

GitHubリリースを公開すると、linux/amd64とlinux/arm64向けにghcr.io/nojusmorkunas/conatus-mcpがビルドされ、その後npmパッケージが公開されます。両方ともリリースされたコミットから生成されるため、リリースは両方のアーティファクトを生成するか、どちらも生成しないかのいずれかです。

リリースにpackage.jsonと一致するvX.Y.Zのタグを付けます。npmジョブは不一致の公開を拒否します。プレリリースはGitHubでそのようにマークすると、betaディストリビューションタグに送られ、latestは最新の安定リリースに残ります。

npm公開はtrusted publishingを使用するため、このリポジトリにはnpmトークンは保存されません。パッケージのnpmjs.com設定ページで、このリポジトリとPublish releaseワークフローにリンクするための一度だけの設定が必要です。

代わりに手動で公開する場合:

npm publish --tag latest   # or --tag beta for a prerelease

ディストリビューションタグを明示的に指定してください。npmは、セマンティックバージョニングのプレリリースサフィックスを持つバージョン（すべての0.x.y-beta.zが該当）に対して、裸のnpm publishを拒否します。

prepublishOnlyはテスト、lint、ビルドチェックを再実行します。publishConfig.accessはすでに設定されているため、--accessフラグは不要です。