Teamwork MCP

Teamwork MCP

Teamwork API に接続し、Teamwork のプロジェクトやタスクを操作するためのシンプルなインターフェースを提供する MCP サーバーです。

機能

• Teamwork API に接続
• プロジェクトとタスクを取得
• タスクを作成、更新、削除
• RESTful API エンドポイント
• エラー処理とログ記録
• Cursor やその他のアプリケーションとの統合に対応した MCP サーバー

前提条件

• Node.js（v14.17 以降。18 以上、または最新の LTS バージョンを推奨）
• npm または yarn
• API アクセス権のある Teamwork アカウント

利用可能な Teamwork MCP ツール

以下のツールを MCP サーバーから利用できます。

プロジェクトツール

• getProjects - Teamwork のすべてのプロジェクトを取得
• getCurrentProject - 現在のプロジェクトの詳細を取得
• createProject - Teamwork に新しいプロジェクトを作成

タスクツール

• getTasks - Teamwork のすべてのタスクを取得
• getTasksByProjectId - Teamwork の特定のプロジェクトにあるすべてのタスクを取得
• getTaskListsByProjectId - Teamwork の特定のプロジェクトにあるすべてのタスクリストを取得
• getTasksByTaskListId - Teamwork の特定のタスクリスト ID にあるすべてのタスクを取得
• getTaskById - Teamwork から ID を指定して特定のタスクを取得
• createTask - Teamwork に新しいタスクを作成
• createSubTask - Teamwork の親タスクの下に新しいサブタスクを作成
• updateTask - Teamwork の既存のタスクを更新
• deleteTask - Teamwork からタスクを削除
• getTasksMetricsComplete - Teamwork の完了済みタスクの合計数を取得
• getTasksMetricsLate - Teamwork の期限超過タスクの合計数を取得
• getTaskSubtasks - Teamwork の特定のタスクに属するすべてのサブタスクを取得
• getTaskComments - Teamwork から特定のタスクのコメントを取得

コメントツール

• createComment - タスク、メッセージ、またはノートに関連するコメントを作成

会社ツール

• getCompanies - オプションのフィルタリングを使用して Teamwork のすべての会社を取得
• getCompanyById - ID を指定して特定の会社を取得
• createCompany - Teamwork に新しい会社を作成
• updateCompany - 既存の会社情報を更新
• deleteCompany - Teamwork から会社を削除

人物ツール

• getPeople - Teamwork のすべての人物を取得
• getPersonById - Teamwork から ID を指定して特定の人物を取得
• getProjectPeople - Teamwork の特定のプロジェクトに割り当てられたすべての人物を取得
• addPeopleToProject - Teamwork の特定のプロジェクトに人物を追加
• deletePerson - Teamwork から人物を削除
• updatePerson - 人物の情報（タイムゾーン、名前、メールアドレスなど）を更新
• getProjectsPeopleMetricsPerformance - 人物のパフォーマンス指標を取得
• getProjectsPeopleUtilization - 人物の稼働率を取得
• getProjectPerson - プロジェクトに参加している特定の人物を取得

レポートツール

• getProjectsReportingUserTaskCompletion - ユーザーのタスク完了レポートを取得
• getProjectsReportingUtilization - CSV および HTML など、さまざまな形式で稼働率レポートを取得

時間ツール

• getTime - すべての時間記録を取得
• getProjectsAllocationsTime - プロジェクトの割り当て時間を取得
• getTimezones - Teamwork で利用可能なすべてのタイムゾーンを取得（ユーザーのタイムゾーン更新時に便利）

インストール

NPX を使用する（推奨）

Teamwork MCP を利用する最も簡単な方法は npx を使用することです。この方法では、リポジトリをクローンしたり、ローカルでコードをビルドしたりする必要はありません。

npx @vizioz/teamwork-mcp

設定オプションを直接渡すこともできます。

npx @vizioz/teamwork-mcp --domain=your-company [email protected] --pass=your-password

設定

認証情報の設定

Teamwork の認証情報は、次の 3 つの方法で指定できます。

1. 環境変数：環境に TEAMWORK_DOMAIN、TEAMWORK_USERNAME、TEAMWORK_PASSWORD を設定します。

2. .env ファイル：必要な変数を含む .env ファイルを作成します。

   TEAMWORK_DOMAIN=your-company
   [email protected]
   TEAMWORK_PASSWORD=your-password
   

3. コマンドライン引数：アプリケーションの実行時に認証情報を渡します。

   npx @vizioz/teamwork-mcp --teamwork-domain=your-company [email protected] --teamwork-password=your-password
   

   または短縮形式を使用します。

   npx @vizioz/teamwork-mcp --domain=your-company [email protected] --pass=your-password
   

ロギングの設定

デフォルトでは、Teamwork MCP サーバーはデバッグとモニタリングに役立つログファイルを logs ディレクトリに作成します。以下の方法でロギングを完全に無効にできます。

1. コマンドライン引数：

   npx @vizioz/teamwork-mcp --disable-logging
   

   または、次の代替形式を使用します。

   npx @vizioz/teamwork-mcp --no-logging
   

2. 環境変数：

   DISABLE_LOGGING=true npx @vizioz/teamwork-mcp
   

ロギングが有効な場合、サーバーは logs ディレクトリに2つのログファイルを作成します。

• error.log - エラーレベルのメッセージのみを含みます
• combined.log - すべてのログメッセージ（情報、警告、エラー）を含みます

各ログファイルには、必要に応じてロギングを無効にする方法を記載したヘッダーが含まれます。

ツールのフィルタリング

以下のコマンドライン引数を使用して、MCP サーバーで利用できるツールを制御できます。

1. 許可リスト：指定したツールのみを公開します。

   npx @vizioz/teamwork-mcp --allow-tools=getProjects,getTasks,getTaskById
   

   または、短縮形式を使用します。

   npx @vizioz/teamwork-mcp --allow=getProjects,getTasks,getTaskById
   

2. 拒否リスト：指定したツール以外のすべてを公開します。

   npx @vizioz/teamwork-mcp --deny-tools=deleteTask,updateTask
   

   または、短縮形式を使用します。

   npx @vizioz/teamwork-mcp --deny=deleteTask,updateTask
   

グループによるツールのフィルタリング

ツールのグループを指定してフィルタリングできるようになりました。これにより、MCP サーバーで利用できるツールをより柔軟に制御できます。利用可能なグループは次のとおりです。

• Projects：プロジェクト関連のツールがすべて含まれます。
• Tasks：タスク関連のツールがすべて含まれます。
• People：ユーザー関連のツールがすべて含まれます。
• Reporting：レポート関連のツールがすべて含まれます。
• Time：時間関連のツールがすべて含まれます。
• Comments：特定のコメント用ツールが含まれます。

ツールのフィルタリングでグループを使用する

許可リストまたは拒否リストでこれらのグループを指定すると、グループ内のすべてのツールを含めたり除外したりできます。例：

1. グループを指定した許可リスト：指定したツールグループのみを公開します。

   npx @vizioz/teamwork-mcp --allow-tools=Tasks,People
   

   または、短縮形式を使用します。

   npx @vizioz/teamwork-mcp --allow=Tasks,People
   

2. グループを指定した拒否リスト：指定したグループ以外のすべてのツールを公開します。

   npx @vizioz/teamwork-mcp --deny-tools=Reporting,Time
   

   または、短縮形式を使用します。

   npx @vizioz/teamwork-mcp --deny=Reporting,Time
   

許可リストも拒否リストも指定されていない場合、デフォルトですべてのツールが公開されます。両方が指定された場合は、許可リストが優先されます。

セキュリティを強化するため、ツールのフィルタリングは次の2つのレベルで適用されます。

1. 利用可能なツールの一覧表示時（許可リストに含まれないツール、または拒否リストに含まれるツールは表示されません）
2. ツール呼び出しの実行時（フィルタリングされたツールの呼び出しはエラーで拒否されます）

Teamwork プロジェクトの設定

現在のソリューションを Teamwork プロジェクトに関連付けるには、次の方法を使用できます。

設定ファイルを使用する

プロジェクトのルートに、次の構成の .teamwork ファイルを作成できます。

PROJECT_ID = YourTeamworkProjectID

このシンプルな設定ファイルは、ソリューションを特定の Teamwork プロジェクトに関連付けます。将来的には、さらに詳細な情報の保存にも使用する場合があります。

設定すると、MCP は Teamwork プロジェクトを検出して現在のソリューションに関連付けられるようになります。これにより、作業中のソリューションに関連するプロジェクトやタスクを取得するために必要な API 呼び出しの数を減らせます。

MCP クライアントへの追加

Cursor

この MCP サーバーを Cursor に追加するには：

0.47 より前のバージョン

1. Cursor の Settings > Features > MCP を開きます 2.「+ Add New MCP Server」をクリックします
2. サーバー名（例：「Teamwork API」）を入力します
3. トランスポートタイプとして「stdio」を選択します
4. サーバーを実行するコマンド npx @vizioz/teamwork-mcp を入力し、上記のとおり認証情報とドメインのコマンドライン引数を追加します。
   • ツールのフィルタリングオプションを指定できます：--allow=getProjects,getTasks または --deny=deleteTask 6.「Add」をクリックします

0.47 より後のバージョン（設定を手動で編集）

"Teamwork": {
  "command": "npx",
  "args": [
    "-y",
    "@vizioz/teamwork-mcp",
    "--domain",
    "yourdomain",
    "--user",
    "[email protected]",
    "--pass",
    "yourPassword"
  ]
}

Cursor でロギングを無効にするには、--disable-logging 引数を追加します。

"Teamwork": {
  "command": "npx",
  "args": [
    "-y",
    "@vizioz/teamwork-mcp",
    "--domain",
    "yourdomain",
    "--user",
    "[email protected]",
    "--pass",
    "yourPassword",
    "--disable-logging"
  ]
}

上記の許可または拒否の引数を追加する場合は、次のように追加します。上記の例はいずれも使用でき、以下に示すようにグループと個別のツールを両方追加することもできます。

"Teamwork": {
  "command": "npx",
  "args": [
    "-y",
    "@vizioz/teamwork-mcp",
    "--domain",
    "yourdomain",
    "--user",
    "[email protected]",
    "--pass",
    "yourPassword",
    "--allow",
    "Tasks,Projects",
    "--deny",
    "getProjectsPeopleMetricsPerformance,getProjectsPeopleUtilization"
  ]
}

これで、Composer の Cursor Agent から Teamwork MCP ツールを利用できるようになります。

Claude Desktop

この MCP サーバーを Claude Desktop に追加するには、Claude Desktop の設定ファイルを編集します。

Windows：%APPDATA%\Claude\claude_desktop_config.json macOS：~/Library/Application Support/Claude/claude_desktop_config.json

次の設定を追加します。

{
  "mcpServers": {
    "teamwork": {
      "command": "npx",
      "args": [
        "-y",
        "@vizioz/teamwork-mcp",
        "--domain",
        "yourdomain",
        "--user",
        "[email protected]",
        "--pass",
        "yourPassword"
      ]
    }
  }
}

Windsurf

この MCP サーバーを Windsurf に追加するには、Cursor と同様の手順で、npx コマンドと認証情報を使用して MCP サーバーの設定を追加します。

ソースからのビルド

注：以下の手順は、プロジェクトへの貢献またはプルリクエストの送信を予定している場合にのみ実行してください。通常の使用では、上記の NPX インストール方法を使用してください。

ローカル開発環境のセットアップ

1. リポジトリをクローンします。

   git clone https://github.com/readingdancer/teamwork-mcp.git
   cd teamwork-mcp
   

2. 依存関係をインストールします。

   npm install
   

3. .env.example ファイルを基に .env ファイルを作成します。

   cp .env.example .env
   

4. .env ファイルに Teamwork の認証情報を設定します。

   PORT=3000
   NODE_ENV=development
   LOG_LEVEL=info
   TEAMWORK_DOMAIN=your-company
   [email protected]
   TEAMWORK_PASSWORD=your-password
   

アプリケーションのビルド

アプリケーションをビルドします。

npm run build

これにより、MCP サーバーとして使用できるように TypeScript コードがコンパイルされます。

MCP サーバーとして実行（ローカルビルド）

Cursor やその他のアプリケーションと連携するために MCP サーバーとして実行する場合、.env ファイルでユーザー名、パスワード、URL を設定している場合、またはそれらを環境変数に保存している場合は、次のように実行します。

注：リポジトリを保存した場所に合わせて、ドライブとパスの詳細を変更してください。

node C:/your-full-path/build/index.js

または、行引数で渡すこともできます。

node C:/your-full-path/build/index.js --teamwork-domain=your-company [email protected] --teamwork-password=your-password

短縮形も使用できます。

node C:/your-full-path/build/index.js --domain=your-company [email protected] --pass=your-password

MCP Inspector の使用

デバッグ用に MCP Inspector を実行するには、次のようにします。

npm run inspector

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

免責事項

このプロジェクトは Teamwork.com と提携しておらず、同社による承認や後援も受けていません。パッケージ名（@vizioz/teamwork-mcp）に「Teamwork」という名前を使用しているのは、Teamwork.com API との互換性を示すための記述上の目的に限られます。